Working with Webhooks
Instant webhook debugging without tunnels — from first payload to production-grade signature verification.
Core Concepts
A webhook is an HTTP callback triggered by an event in your provider. Unlike polling, the source pushes data to your endpoint the moment something happens — a new order in Shopify, a completed payment in Stripe, or a pushed commit in GitHub.
Event-Driven Delivery
Hookly captures every inbound request and stores the full payload, headers, and timestamp. You can replay event order.created from March 14 or scrub a malformed JSON body from a misconfigured SendGrid integration — all without touching your production server.
Endpoint Lifecycle
Your endpoint must return 200 OK within the provider's timeout window (typically 5–30 seconds). Hookly simulates slow responses, lets you inject custom delays, and shows exactly where Stripe, GitHub, or Pipedream give up and queue a retry.
Idempotency & Replay
Providers retry failed deliveries. Hookly tags each attempt with a unique delivery ID, so you can build idempotent handlers — process payment_intent.succeeded only once, even if Stripe sends it three times across a 10-minute window.
Signatures & Verification
Every webhook you accept in production must be verified. An unverified endpoint is an open door — anyone who guesses your URL can inject fake events, trigger chargebacks, or poison your database with spoofed payloads.
HMAC-SHA256 is the industry standard. The provider signs the raw request body with a shared secret, then attaches the resulting hex string to a header — X-Stripe-Signature, X-Hub-Signature-256, or X-SendGrid-Eventwebhook-Signature, depending on the source. Your server rebuilds the HMAC from the received body and secret, compares it against the header, and rejects anything that does not match.
Stripe Signature Format
Stripe sends X-Stripe-Signature: t=1710347821,v1=a1b2c3...,v0=d4e5f6.... The timestamp t prevents replay attacks. Hookly parses this header automatically, shows the computed HMAC next to the received one, and highlights mismatches in red. You can also toggle a "strict timestamp" mode that rejects signatures older than 300 seconds.
GitHub HMAC Verification
GitHub attaches X-Hub-Signature-256: sha256=<hex> to every event. Hookly lets you paste your repository webhook secret and validates incoming payloads in real time. When you're testing locally, Hookly generates a temporary secret and prints a Node.js snippet you can drop into your route handler.
Error Handling & Dead Letters
Not all failures are signature mismatches. Hookly logs HTTP 5xx responses, timeout expirations, and TLS handshake failures separately. You can configure a dead-letter queue URL — when a webhook fails three times across different providers, Hookly forwards the raw payload to your fallback endpoint so nothing slips through the cracks.
A practical rule: always read the raw body before parsing JSON. If you mutate the body string — trimming whitespace, changing encoding, or re-serializing — the HMAC you compute will diverge from the provider's. Hookly preserves the exact byte sequence and shows a hex dump side by side with the UTF-8 text, so you can spot BOM characters, stray newlines, or gzip encoding issues that silently break verification.