workos webhook signature mismatch error

Not specified by the original author.

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.

Not specified by the original author.

Verify against the raw request body bytes: capture the body before any JSON parsing (in Next.js disable body parsing for the route, in Express use the raw-body middleware). Split the WorkOS-Signature header on the comma into t= and v1=, reject timestamps older than your tolerance (default a few minutes, in milliseconds) to block replays, then HMAC-SHA256 the string timestamp + '.' + rawBody with the webhook secret and compare hex digests with a timing-safe compare. For local testing register an ngrok public URL, not YOUR_HOST, since WorkOS rejects non-public hostnames at save time.

Context: Official docs (Sync data with webhooks): documents a gotcha that trips agents verifying WorkOS webhook signatures. The WorkOS-Signature header carries t=[milliseconds], v1=[hmac], and the signature is HMAC-SHA256 hex over the concatenation of the timestamp, a dot, and the request body as a utf-8 string. Agents that parse the body to JSON first and re-stringify it compute the HMAC over different bytes and fail verification on every delivery. The docs also note the endpoint URL must resolve to a public IP; WorkOS rejects private or internal hostnames when you save the endpoint.

Matched source

Source: Published skill Original query: "WorkOS webhook signatures need the raw body, not parsed JSON" Key terms: body, json, need, parsed, signatures, webhook, workos

Source: Official docs (Sync data with webhooks): documents a gotcha that trips agents verifying WorkOS webhook signatures. The WorkOS-Signature header carries t=[milliseconds], v1=[hmac], and the signature is HMAC-SHA256 hex over the concatenation of the timestamp, a dot, and the request body as a utf-8 string. Agents that parse the body to JSON first and re-stringify it compute the HMAC over different bytes and fail verification on every delivery. The docs also note the endpoint URL must resolve to a public IP; WorkOS rejects private or internal hostnames when you save the endpoint.

Verified resolution: Verify against the raw request body bytes: capture the body before any JSON parsing (in Next.js disable body parsing for the route, in Express use the raw-body middleware). Split the WorkOS-Signature header on the comma into t= and v1=, reject timestamps older than your tolerance (default a few minutes, in milliseconds) to block replays, then HMAC-SHA256 the string timestamp + '.' + rawBody with the webhook secret and compare hex digests with a timing-safe compare. For local testing register an ngrok public URL, not YOUR_HOST, since WorkOS rejects non-public hostnames at save time.

Source URL: https://workos.com/docs/events/data-syncing/webhooks

Not specified by the original author.

Stop the agent misrouting webhook events to the wrong tenant

TL;DR

Derive the tenant from the signed webhook payload itself, never from the URL path, query string, or whatever the agent guessed. Verify the signature first, extract the tenant id from inside the verified payload, then route.

The problem

webhook received on /hooks/acme-corp
payload (verified): tenant_id = "globex-inc"
event applied to: acme-corp workspace
result: globex onboarding marked complete in acme's workspace

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=agent misrouted webhook events wrong tenant multi-tenant onboarding"

Fix it

Step 1: Verify the signature before touching anything

Validate the webhook signature with the shared secret for the endpoint before parsing or routing. Reject anything that fails verification.

Expected: only genuinely provider-sent events reach your routing logic.

Step 2: Extract the tenant id from inside the verified payload

Read the tenant identifier from the verified payload body (tenantid, accountid, or the provider's equivalent). This is the only tenant value you trust.

Expected: the tenant id is known and comes from signed data.

Step 3: Route strictly on that tenant id

Look up the workspace by the payload tenant id and apply the event there. Ignore tenant hints in the URL path or query params; treat a mismatch between path and payload as a routing error, not a tie to break.

Expected: every event lands in the workspace that matches its signed tenant id.

Step 4: Log path-vs-payload mismatches as security events

When the URL tenant and the payload tenant disagree, drop the event and alert. That pattern is either a misconfigured sender or someone probing.

Expected: mismatches are visible and noisy instead of silently "resolved" by picking one.

Step 5: Replay a cross-tenant event in staging

Send a signed event whose payload tenant differs from the URL tenant.

Expected: the event is rejected or routed to the payload tenant, and an alert fires. It never touches the URL tenant's workspace.

When this applies

• Webhook events update the wrong customer's onboarding state
• The endpoint uses per-tenant URLs or a tenant query param for routing
• Onboarding state (steps, checklists, provisioning) is tenant-scoped

When it doesn't

• Webhooks fail signature verification entirely (fix the secret first)
• A single-tenant app where routing is not a concept
• Events are delayed or duplicated but land in the right tenant

Compatibility

Stripe, GitHub, Slack, and Segment webhooks; any multi-tenant SaaS with per-customer onboarding state. The pattern holds for every signed webhook.

Variant phrasings

webhook applied to wrong workspace during onboarding

Same fix. The workspace must come from the verified payload, full stop.

multi-tenant webhook routing mixed up customer events

Audit every place the agent reads tenant from the request instead of the payload. There is usually more than one.

Why it happens

Per-tenant webhook URLs feel like routing - /hooks/acme-corp must be for acme. But URLs are cheap to get wrong: a provider misconfiguration, a copied endpoint, or an agent that registered one URL for every tenant can all deliver tenant A's event to tenant B's path. The payload is the only signed statement of which tenant the event belongs to, and routing on anything else is a guess dressed up as logic.

Edge cases

• Providers that do not include a tenant id in the payload: join on a verified account identifier (connected account id, installation id) instead
• Shared secrets across tenants: rotate to per-tenant secrets so a leak cannot forge cross-tenant events
• Batched payloads with mixed tenants: split and route each event individually

If it still fails

• Capture the raw payload, the signature header, the URL tenant, and the payload tenant before changing anything else.
• Reproduce with one signed test event so you are not debugging a crowd.
• Check the provider status page; delivery outages look exactly like routing bugs.

Prevention

• Webhook handlers take the tenant id as an explicit verified parameter, never from ambient state.
• Integration tests cover cross-tenant payloads for every webhook endpoint.
• Alert on any payload-vs-path tenant mismatch the day it happens.

Provenance

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

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

Thread query: agent misrouted webhook events wrong tenant multi-tenant onboarding

TL;DR: Derive the tenant from the signed webhook payload itself, never from the URL path, query string, or whatever the agent guessed. Verify the signature first, extract the tenant id from inside the verified payload, then route.