# workos webhook signature mismatch error

## TL;DR
The HMAC was computed over bytes you no longer have, or with a secret you do not hold. Capture the raw request body before parsing, pull the webhook secret for that exact endpoint from the WorkOS dashboard, and verify with WorkOS's SDK helper. Replay a test webhook and confirm verification passes.

```text
workos webhook signature mismatch error
```

## Use this when

- WorkOS webhooks fail signature verification
- Verification works for one endpoint but not another
- Recently added a second WorkOS webhook endpoint

## Not for this skill when

- WorkOS API calls failing (separate from webhooks)
- Verified events with missing expected fields (payload handling)
- Webhooks never arriving (URL or firewall issue)

## Steps

### Step 1: Capture the raw body

Make sure the handler keeps the raw request bytes before any parsing middleware touches them. Expected: you verify the identical bytes WorkOS signed.

### Step 2: Use the right secret

In the WorkOS dashboard, open the specific webhook endpoint and copy its secret; endpoints each have their own. Expected: the secret belongs to the endpoint that sent the event.

### Step 3: Verify with the SDK helper

Use the WorkOS SDK's signature verification function rather than hand-rolled HMAC. Expected: verification returns success for genuine events.

### Step 4: Check header and timestamp handling

Confirm you are reading the signature header WorkOS sends and honoring its timestamp tolerance. Expected: no stale or replayed event is wrongly accepted or rejected.

### Step 5: Replay a test webhook

Send a test event from the WorkOS dashboard. Expected: it verifies and your handler processes it.

## Tool compatibility

WorkOS webhooks; WorkOS server SDKs (signature verification); webhook endpoints with raw-body access.

## Variant phrasings

### Variant 1

workos webhook signature verification failed

### Variant 2

workos signature mismatch webhook secret

### Variant 3

workos webhook 400 invalid signature fix

## Why it happens

WorkOS signs each webhook endpoint's payloads with that endpoint's own secret, so the most common failure is simply using the wrong secret. It is usually another endpoint's secret, the API key, or a stale pre-rotation value. The second is byte fidelity: frameworks that parse JSON on the way in hand you an object, and re-serializing it changes whitespace or key order, breaking the HMAC. The SDK's verify helper exists precisely to remove both failure modes, but only if it receives the raw bytes and the right secret. Teams that hand-roll verification to avoid a dependency usually reintroduce the exact bugs the helper prevents.

## Edge cases / pitfalls

- Each WorkOS environment and endpoint has its own secret; label them clearly in your secret store.
- Copying the secret with trailing whitespace is a classic; trim and compare lengths when debugging.
- Test webhooks from the dashboard use the same signing path as real events, so a passing test is meaningful.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_B5C3c99aNGWC4fPXjcDg6g