Webhook Guides

Webhook Headers

Webhook headers carry the operational context that payloads often do not: event type, delivery id, signature, timestamp, content type, provider identity, and sometimes a shop, tenant, or subscription identifier.

FastHook stores inbound headers on requests, lets you route by header values, and can add outbound destination auth headers when delivering events to receivers. Header inspection is one of the fastest ways to debug a failed webhook.

Common header families

FamilyExamplesUse
Event typeX-GitHub-Event, X-Shopify-TopicRoute events without parsing the full payload.
Delivery idX-GitHub-Delivery, X-Shopify-Webhook-IdDeduplicate and correlate retries.
SignatureStripe-Signature, X-Hub-Signature-256Verify the sender against the raw body.
TimestampX-Slack-Request-TimestampReject stale replay attempts.
Content typeapplication/json, application/x-www-form-urlencodedChoose parsing behavior safely.

Route by headers

Header filter
{
  "type": "filter",
  "headers": {
    "x-github-event": { "$eq": "pull_request" },
    "x-github-delivery": { "$exists": true }
  }
}

Signature headers

Signature headers usually cover the raw request body. If a receiver verifies against parsed JSON or a modified body, the signature will fail even when the secret is correct.

  • Store and compare the exact raw body for HMAC-based providers.
  • Use timestamp tolerance for providers that include signed timestamps.
  • Log signature failure causes without leaking secrets.
  • Keep separate secrets for production, staging, and local sources.

Outbound headers

Destination auth is a separate boundary. FastHook can send a custom header, OAuth token, or FastHook destination signature so your receiver can verify that the delivery came through FastHook.

Custom destination header
{
  "auth_type": "CUSTOM_HEADER",
  "auth": {
    "header_name": "x-internal-webhook-key",
    "header_value": "receiver-secret"
  }
}

Debug checklist

  1. Compare provider docs against the captured request headers.
  2. Confirm header names are treated case-insensitively.
  3. Check whether proxies or frameworks strip or rewrite headers.
  4. Use header filters before body filters when the provider exposes a reliable event header.
  5. Use delivery ids as correlation keys across FastHook, provider logs, and receiver logs.

Header normalization tips

HTTP header names are case-insensitive, but application code and logs often display them differently. Pick one normalized form for filters and examples, then compare values rather than relying on visual casing in screenshots.

Also watch for duplicate headers. Some providers or proxies can send repeated values, and frameworks may join them into one comma-separated string. For signature verification, use the exact header behavior your provider documents.

  • Normalize filter header names to lowercase for predictable matching.
  • Store provider delivery ids even when the payload has its own event id.
  • Do not use User-Agent as an authentication boundary.
  • Prefer signed headers or provider tokens for trust decisions.

Related guides