Testing a webhook before writing any code
A webhook is an HTTP request that a service sends to your URL when something happens, such as a payment succeeding or code being pushed. Before you build a handler, you need to know exactly what that request looks like, and documentation examples do not always match reality.
- Copy your URL and paste it into the service’s webhook settings, such as Stripe’s Workbench, GitHub’s repository Settings › Webhooks, or Shopify’s notification settings.
- Trigger a real test event from that service, or press Send test to check the URL itself works.
- Open the request to see the method, headers, query string and body, with JSON formatted and form fields shown as a table.
- Use Copy as cURL to send the identical request to your own server or to localhost while you develop.
Headers worth checking
- Content-Type: most services send application/json, but Slack slash commands and Twilio send form data (application/x-www-form-urlencoded), which needs a different parser.
- The event name: GitHub puts it in X-GitHub-Event, while Stripe and Shopify put it inside the body or a topic header.
- A delivery or event ID, which you need for spotting duplicates.
- The signature header, such as Stripe-Signature, X-Hub-Signature-256 or X-Shopify-Hmac-Sha256.
Header names are case-insensitive, and some proxies change their case, so compare them without regard to case in your code.
Checking a webhook signature
A signature proves the request came from the service and was not changed. The service computes an HMAC-SHA256 of the request body with a shared secret, and your code repeats the calculation and compares:
- GitHub sends sha256= followed by the HMAC of the raw body in hex.
- Shopify sends the HMAC of the raw body in Base64.
- Stripe signs the timestamp, a full stop and the body together, and sends t=…,v1=… so you can also reject old replays.
Always use the raw bytes as received. Parsing the JSON and turning it back into text changes spacing or key order, and the signature then fails. The body shown here is stored byte for byte, so you can copy it into the HMAC generator with your secret and confirm you get the same value as the header.
Retries, timeouts and duplicate events
Services treat any response other than a 2xx, or no response in time, as a failure and send the event again. GitHub gives up on a delivery after 10 seconds, and Stripe keeps retrying live events for up to three days. A good handler therefore:
- Answers with 200 straight away and does slow work, such as sending emails, in a background job.
- Stores each event ID and ignores one it has already processed, since the same event can arrive twice.
- Does not rely on events arriving in order; it reads the timestamp or fetches the latest state from the API.
Requests sent to the tester are stored on the server until they expire, and anyone who knows the URL can post to it. Use test-mode events, keep the URL to yourself, and press New URL when you are done.