Webhook signature mismatch: compare the secret fingerprint first
When a Sume webhook signature will not verify, compare x-sume-webhook-secret-fingerprint with the dashboard fingerprint. It is safe to paste into a ticket.
When a Sume webhook signature will not verify, compare fingerprints before anything else. Every delivery carries an x-sume-webhook-secret-fingerprint header, and the dashboard shows the same fingerprint beside the secret, so you can confirm both sides hold the same secret without sending the secret anywhere.
Where do I find each fingerprint?
On the delivery, read the x-sume-webhook-secret-fingerprint header. For Format runs, webhook_delivery.signing_secret_fingerprint on the run receipt repeats it. On your side, open the Webhooks tab at /dashboard/webhooks, where the fingerprint is shown next to the secret. The docs call it the one part of this that is safe to paste into a ticket, unlike the secret.
What do the two outcomes tell me?
Reading the secret through the API needs any API key carrying account:read.
| Comparison | Meaning | Next step |
|---|---|---|
| Different | Your receiver holds a different secret than the one signing | Re-read the secret from the dashboard or GET /v1/webhooks/signing-secret and update SUME_COM_WEBHOOK_SIGNING_SECRET |
| Same | The secret is not the problem | Check the raw body, the timestamp and the await |
Why does the fingerprint change after I rotate?
The header names the new secret from the moment you rotate, including during the 24-hour window when Sume signs each delivery with both secrets. So it tells you which secret to move to, not which ones are still accepted. In that window the signature header carries sume-v1=<new>,sume-v1=<old>, so a hand-rolled verifier that compares the header for equality fails on every delivery.
What if the fingerprints match and it still fails?
Verify against the raw request body, before any JSON parse or re-serialize. Check that your clock is inside the replay window, which defaults to 300 seconds in verifyWebhook, and that you await the async check. A Redeliver is signed with the same secret, so the fingerprint on a redelivery is the same 12 characters as the original.
What is safe to paste into a support ticket?
The fingerprint, and nothing else from the secret. The signing secret is derived for your workspace, so a valid signature proves the delivery was signed for you rather than for anyone holding a shared platform secret. Store the secret the way you store the API key, and note that it is not the API key: verifyWebhook takes no client and makes no request.
Do job webhooks and run webhooks use the same secret?
Yes. Job webhooks and run webhooks share that one secret, so a single verifier and a single fingerprint comparison cover both. Pair the two checks: fingerprint first to rule out a wrong or stale secret, then the raw body and timestamp to rule out everything else.
Sources
Related posts
More in Developers
- Webhook send test vs redeliver: which one replays a real job?
Send test posts a dummy webhook.test payload to a URL you type. Redeliver re-sends a real terminal event and does not use one of the automatic 10 attempts.
- Webhook status OK but output null? Read outcome: degraded
A Sume run webhook can say status OK while output is null. The run completed and billed; outcome is degraded and output_error says why. How to branch on it.
- OpenAI Agents API vs a custom agent API for async runs
OpenAI's Agents API keeps durable sessions; Sume Agent Completions return a 202 receipt to poll or receive by webhook. Where each fits, and how they differ.
- Which MCP server lets Claude Code or Cursor generate video and images?
MCP servers that let Claude Code and Cursor make video and images: Sume, fal, Replicate, Runway, Higgsfield. Endpoints, sign-in, billing, setup.
Written by Sume