Verify Contentful webhooks

​

Get the signing secret

​

Register it on your endpoint

# read from a no-echo prompt (or piped stdin) — never an argv flag
printf %s "$CONTENTFUL_SIGNING_SECRET" | wbhk endpoints add-provider-secret <endpoint-id> \
  --provider contentful

curl https://api.webhook.co/v1/endpoints/<endpoint-id>/provider-secrets \
  -H "Authorization: Bearer $WEBHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"contentful","secret":"<your-value>"}'

await webhook.endpoints.providerSecrets.add({
  endpointId,
  provider: "contentful",
  secret: process.env.CONTENTFUL_SIGNING_SECRET!,
});

​

How the signature is checked

• Signed message — a canonical request METHOD\nNORMALIZED_PATH\nHEADERS_SECTION\nRAW_BODY, where HEADERS_SECTION is exactly the headers named in x-contentful-signed-headers (key:value, key lowercased, sorted by key, joined by ;).
• Algorithm — HMAC-SHA256, hex-encoded.
• Key — registered secret is a 64-char string used verbatim as the UTF-8 HMAC key.
• Signature format — lowercase-hex 32-byte HMAC-SHA256 MAC.
• Timestamp — read from the x-contentful-timestamp header.
• Also signed — x-contentful-signed-headers. These header values are folded into the signed message, so they must reach us unmodified.

​

Replay window

​

What makes this one different

• The signed message’s header section is DYNAMIC: x-contentful-signed-headers lists which headers are folded in, so the canonical string shape varies per request.
• Canonical = METHOD\nNORMALIZED_PATH\nHEADERS_SECTION\nRAW_BODY; signed headers are key:value, key lowercased+trimmed, sorted by key, joined by ; (the signed-headers HEADER itself uses ,).
• One-sided 30-second TTL against x-contentful-timestamp (milliseconds); the timestamp is itself a signed header, so replay is also bound in the signature.

​

Confirm

wbhk events list <endpoint-id> --status verified