Webhook standard verify

webhook-standard-verify · version 1.0.0 · Hashing & signatures · free, no key needed

Verify a Standard Webhooks (Svix/Clerk/Resend) webhook-signature header against its id.timestamp.payload signing string.

Use when you need to: verify a standard webhooks signature · check webhook-signature header · validate a svix or clerk webhook.

Decide before calling

Read the versioned contract and the supported scope below. Reuse webhook-standard-verify@1.0.0 when your input, required output and limits match it. Choose another approach for an unsupported operation.

Explain the choice

"I can use webhook-standard-verify@1.0.0 for verify a standard webhooks signature. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

Supported

• verify a standard webhooks signature
• check webhook-signature header
• validate a svix or clerk webhook
• standard webhooks spec verification
• whsec_ secret signature check
• clerk or resend webhook signature check

Not supported

• computing a fresh webhook-signature header for a test delivery (see webhook-signature-compute)
• verifying any other vendor webhook scheme (see webhook-stripe-verify, webhook-slack-verify, webhook-twilio-verify)

Behavior

• secret decoding: strip a leading 'whsec_' if present, then base64-decode the remainder, tolerant of an already-correctly-padded or unpadded value. An empty result, or a string that still fails to base64-decode, is invalid_input.
• signed content = webhook_id + '.' + webhook_timestamp (the exact digit string given) + '.' + payload (raw, never re-serialized), HMAC-SHA256'd with the decoded secret; the resulting bytes are base64-encoded (standard, padded) to form the expected token value.
• webhook_signature is split on ASCII spaces into tokens of the form '<scheme>,<base64>'; only tokens whose scheme is exactly 'v1' are compared (any other scheme is skipped, not treated as an error) -- if no 'v1' token is present at all, reason is 'no_v1_signature'. Each v1 token's base64 part is constant-time-compared to the expected value; the FIRST index (0-based, left to right in webhook_signature) that matches is matched_index, and any one match makes the whole call valid -- if none match, reason is 'signature_mismatch'.
• When now is given: timestamp_checked is true, and the tool fails with reason 'timestamp_outside_tolerance' when abs(now - webhook_timestamp) > tolerance_seconds (an ABSOLUTE, both-directions check), checked only after a signature match succeeds. When now is omitted, timestamp_checked is false and no freshness check runs.
• secret is never echoed in the output or in any error details.

Input

• payload (string, required): max length 262144
• webhook_id (string, required): min length 1; max length 256
• webhook_timestamp (string, required): pattern ^[0-9]{1,16}$
• webhook_signature (string, required): min length 1; max length 4096
• secret (string, required): min length 1; max length 512
• now (integer, optional): min 0; max 99999999999
• tolerance_seconds (integer, optional): min 0; max 86400; default 300

Output

• valid (boolean, required)
• reason (one of "no_v1_signature", "signature_mismatch", "timestamp_outside_tolerance", null, required)
• timestamp_checked (boolean, required)
• matched_index (integer or null, required): min 0

Limits

• max payload bytes: 262144

Example

Request input:

{
  "payload": "{\"test\":1}",
  "webhook_id": "msg_1",
  "webhook_timestamp": "1614265330",
  "webhook_signature": "v2,decoy",
  "secret": "MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

Response:

{
  "result": {
    "valid": false,
    "reason": "no_v1_signature",
    "timestamp_checked": false,
    "matched_index": null
  }
}

How to call it

MCP

Connect https://computefirst.net/mcp (setup), then call execute with:

{
  "id": "webhook-standard-verify",
  "version": "1.0.0",
  "input": {
    "payload": "{\"test\":1}",
    "webhook_id": "msg_1",
    "webhook_timestamp": "1614265330",
    "webhook_signature": "v2,decoy",
    "secret": "MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/webhook-standard-verify/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"payload":"{\"test\":1}","webhook_id":"msg_1","webhook_timestamp":"1614265330","webhook_signature":"v2,decoy","secret":"MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"}'

The machine-readable contract is at /v1/tools/webhook-standard-verify/versions/1.0.0.

CLI

node cli.mjs run webhook-standard-verify 1.0.0 --input input.json --base-url https://computefirst.net

Get the client at /clients/cli/.

Related tools

• Webhook stripe verify: Verify a Stripe webhook's Stripe-Signature header against a raw payload, with secret-rotation and tolerance support.
• Webhook slack verify: Verify a Slack request's X-Slack-Signature against its raw body and timestamp, with an absolute replay-window check.
• Hmac verify: Recompute an HMAC and compare it, constant-time, to a signature that may carry a literal prefix and be truncated.
• Webhook signature compute: Compute a signed webhook header for Stripe, Slack, Standard Webhooks, Twilio, GitHub or Shopify.
• Merkle proof verify: Recompute a Merkle root (RFC 9162 or Bitcoin) from one leaf and its audit path, and compare it to a claimed root.
• Webhook twilio verify: Verify a Twilio X-Twilio-Signature against a URL and form params or a JSON body, trying Twilio's port-variant URLs.