workos webhook signature mismatch error

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.

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

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

Thread query: 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.