# Webhook Signature Verifier (/docs/experiments/webhook-signature-verifier)



Accept a raw payload, secret, signature header value, and algorithm. Computes the expected HMAC (Stripe/GitHub `sha256=` hex style) and returns whether it matches using a **timing-safe compare**.

## Features [#features]

* POST /verify - HMAC-SHA256 verification with clear comparison explanation
* Supports prefixed signatures (`sha256=...`) and raw hex
* Uses Web Crypto at the edge; no external libraries

## API Reference [#api-reference]

### POST /verify [#post-verify]

**`payload`** `string` (required) - Raw request body as received.

**`secret`** `string` (required) - Shared signing secret.

**`signature`** `string` (required) - Signature from the webhook header.

**`algorithm`** `string` (optional) - Default `sha256`.

#### Example Request [#example-request]

```bash
curl -X POST "https://your-worker.workers.dev/verify" \
  -H "Content-Type: application/json" \
  -d '{"payload":"{\"id\":1}","secret":"whsec_test","signature":"sha256=..."}'
```

#### Success Response [#success-response]

```json
{
  "match": true,
  "algorithm": "sha256",
  "expectedSignature": "sha256=...",
  "providedSignature": "sha256=...",
  "explanation": "Timing-safe comparison of 32-byte HMAC digests returned match."
}
```

#### Error Codes [#error-codes]

* `400` - `INVALID_BODY`, `MISSING_FIELD`, `INVALID_ALGORITHM`

## Use Cases [#use-cases]

* Debug Stripe, GitHub, or Shopify webhook signature mismatches
* Learn timing-safe HMAC verification patterns for Workers
* Validate signing logic before wiring production webhook handlers

## Limitations [#limitations]

* HMAC-SHA256 only in this experiment
* Secrets are sent in the request body; use only for debugging, not production traffic
* No replay protection or timestamp validation

## Deployment [#deployment]

<Steps>
  <Step>
    ### Click the deploy button [#click-the-deploy-button]

    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/webhook-signature-verifier)
  </Step>

  <Step>
    ### Configure bindings [#configure-bindings]

    See `wrangler.json` and the experiment README for required bindings.
  </Step>

  <Step>
    ### Test your deployment [#test-your-deployment]

    See the experiment README for curl examples.
  </Step>
</Steps>

## Local Development [#local-development]

```bash
cd apps/experiments/webhook-signature-verifier
npm install
npm run dev
```

## Configuration [#configuration]

No bindings required beyond the Workers runtime.

## Cloudflare Features Used [#cloudflare-features-used]

* **[Workers](https://developers.cloudflare.com/workers/)**
* **[Web Crypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/)**