webhook security

21 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Webhook transport security: HTTPS and TLS requirements

All webhook traffic must be encrypted in transit using HTTPS. Require TLS 1.2 or higher; disable TLS 1.0, 1.1, and weak cipher suites. Use certificates from a trusted Certificate Authority and reject self-signed certificates in production. As a publisher, validate the subscriber's certificate before delivery.

Webhook HMAC-SHA256 signature verification: publisher requirements

Publishers must generate a random signing secret of at least 32 bytes per registered webhook. Compute HMAC-SHA256 over the raw request body, including a timestamp. Send the hex digest in a dedicated header such as X-Hub-Signature-256.

Webhook HMAC-SHA256 signature verification: subscriber requirements

Subscribers must read the raw request body before the framework parses it. Recompute the HMAC locally and compare using a constant-time function like hmac.compare_digest or MessageDigest.isEqual—never use ==. Return 401 on signature mismatch and do not reveal why validation failed.

Webhook signature verification pitfall: canonicalization

Verify signatures against the exact raw bytes received. Do not reformat or pretty-print JSON, reorder fields, change whitespace or line endings, or convert character encodings before verification, as any transformation can invalidate the signature.

Webhook secret management: storage and rotation

Store signing secrets in a secrets manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager). Never hard-code secrets in source code, config files, or container images. Use per-webhook secrets rather than a single shared secret. Use a dual-secret window for rotation: generate the new secret, configure the publisher to sign with both old and new secrets (or include both signatures in the header), update the subscriber to accept either, then after confirming delivery with the new secret, revoke the old one. Return 4xx on requests signed only with the revoked secret.

Webhook secret management: redaction from logs

Redact secrets from all logs and error responses to prevent leakage.

Webhook authentication layering: defence in depth methods

Layer one or more of the following authentication mechanisms on top of HMAC signing: Mutual TLS (mTLS) for high-assurance machine-to-machine pipelines; Bearer token or API key for simple integrations, stored in secrets manager with regular rotation; OAuth 2.0 for user-delegated flows with validation of exp, aud, iss on every request; IP allowlisting as an additional layer, though it is fragile when publisher IPs rotate and must not be a sole control.

Webhook replay attack protection: timestamp and deduplication

Include a Unix timestamp in the signed material and transmit it in the signature header (e.g., t=<unix_ts>,v1=<digest>). Reject requests whose timestamp differs from server time by more than ±5 minutes. For higher assurance, cache recently seen event IDs for at least the length of the timestamp validation window (e.g., Redis with TTL ≥ 5 minutes) and reject duplicates.

Webhook idempotency: duplicate event handling

Use the platform-provided event ID (e.g., event_id, delivery_id) as an idempotency key. Persist processed event IDs and skip re-processing on a duplicate. Return HTTP 200 immediately for known duplicates to stop re-delivery. Design downstream operations (database writes, emails, payments) to be idempotent by default.

Webhook SSRF prevention on publisher side: IP blocking

When delivering webhooks to user-supplied URLs, resolve the hostname to an IP before delivery and block: Loopback 127.0.0.0/8 and ::1; RFC 1918 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16; Link-local and Cloud IMDS 169.254.0.0/16 (includes 169.254.169.254); and internal DNS names such as metadata.google.internal.

Webhook SSRF prevention on publisher side: DNS rebinding and redirects

Re-resolve the hostname immediately before the HTTP request to prevent DNS rebinding. Disable HTTP redirects or validate every redirect target against the same SSRF blocking rules. Allowlist schemes to accept https:// only; block file://, gopher://, ftp://, and other schemes.

Webhook rate limiting: publisher and subscriber controls

Publisher must implement per-subscriber delivery rate limits with exponential back-off and a maximum retry count. Subscriber must apply rate limiting at the API gateway or application layer, return 429 Too Many Requests with a Retry-After header when the limit is exceeded, and decouple ingestion from processing with an async queue (SQS, Kafka, RabbitMQ) to absorb traffic spikes without dropping events.

Webhook input validation: payload handling

Treat every incoming payload as untrusted input regardless of source IP or signature validity. Reject requests with an unexpected Content-Type. Enforce a maximum payload size to prevent memory exhaustion. Validate the payload against a strict schema with allowlisted fields and typed values before processing. Apply context-appropriate output encoding such as parameterised queries for SQL or escaped output for HTML rendering.

Webhook HTTP method restriction

Webhook endpoints must accept only POST requests. Return 405 Method Not Allowed for all other methods. Explicitly disable PUT, DELETE, PATCH, TRACE, and OPTIONS unless specifically required.

Webhook CSRF considerations: exemption strategy

Webhook endpoints must be exempted from framework CSRF token checks because the publisher is a server, not a browser, and cannot supply a CSRF token. HMAC signature verification serves as the functional equivalent of CSRF protection. Scope the CSRF exemption to the webhook route only and do not disable it globally. Ensure HMAC verification is in place before granting the exemption.

Webhook error handling: fail securely

Return 200 only after the event has been acknowledged (queued or processed). Return 400 for malformed payloads and 401/403 for signature failures. Never return stack traces or verbose error details in HTTP responses; log them server-side. Set up alerting for events that repeatedly fail processing in the dead-letter queue.

Webhook logging and monitoring: what to log

Log timestamp, source IP, HTTP method, response status, event ID, event type, and processing latency. Do not log full request bodies (which may contain PII), signing secrets, or raw Authorization header values.

Webhook logging and monitoring: alerts

Alert on a spike in signature verification failures (which may indicate scanning or an attacker probing the endpoint), sustained 4xx/5xx delivery errors (which may indicate processing failures or upstream misconfiguration), and deliveries arriving from unexpected source IPs.

Webhook event ordering: out-of-order delivery handling

Webhook events may arrive out of order due to retries, queueing, or network delays. Do not assume chronological delivery order. Use event timestamps or sequence numbers in the payload when ordering matters. When consistency is critical, fetch the current object state from the publisher API rather than relying solely on the event payload.

Webhook security testing checklist

Test cases for webhook security include: invalid or missing signature (endpoint must return 401, not 200); replay attempt (resubmit a captured request after the tolerance window; endpoint must reject it); duplicate event ID (send the same event twice; only one should be processed); oversized payload (endpoint must return 400 or 413); SSRF callback URL on publisher side (attempt to register http://169.254.169.254/ as a webhook URL; delivery must be blocked); secret rotation (verify both old and new secret are accepted during the dual-secret window, and only the new one is accepted after revocation).

Webhook threat model summary

Primary controls for webhook threats: spoofed/forged events use HMAC signature verification; replay attacks use timestamp plus event-ID deduplication; secret leakage uses secrets manager and log redaction; SSRF via callback URL uses IP/hostname allowlisting on publisher; denial of service uses rate limiting and async queues; duplicate processing uses idempotent event handlers; man-in-the-middle uses TLS 1.2+ with valid CA certificate; payload injection uses input validation and schema enforcement.

Give your agent this brain