Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A webhook is an HTTP event notification sent by one service to an endpoint you configure. When a subscribed event occurs, the sender sends a request; your application verifies and acknowledges it, then processes the event. The pattern is simple, but delivery timing, retries, signatures, duplicates, and ordering vary by provider—and those differences matter in production.
How a webhook works
A webhook reverses the direction of a typical API interaction. Instead of your application repeatedly asking a service whether anything changed (polling), the service sends a request when an event occurs. For example, an application might receive a notification when an order is created or a repository changes.
There is no single universal webhook protocol. Providers define their own event envelopes, headers, signature schemes, acknowledgement deadlines, retry schedules, and recovery tools. Shopify, for example, documents HTTPS deliveries as POST requests with JSON bodies and metadata headers; other delivery options and providers can behave differently. See Shopify’s delivery structure.
Recommended Free Tools
The receiver’s request lifecycle
- Receive the request. Make the endpoint reachable over HTTPS and accept the method and content type the provider documents.
- Preserve the body for verification. If the provider signs the request body, retain the exact raw bytes before middleware parses or transforms them.
- Verify authenticity. Check the signature using the provider’s specified header, algorithm, secret, and input. Do not trust the payload before this succeeds.
- Check what happened. Validate the event type and any action before taking an action. A provider may support event types your application does not use.
- Persist or enqueue the delivery durably. Record enough information to recover and process it after a crash. A quick response without durable acceptance can still lose the event.
- Acknowledge promptly, then process safely. Return the response the provider expects within its deadline. Perform slow work asynchronously, with duplicate and ordering safeguards.
The six ways webhooks break in production
1. The endpoint cannot be reached
DNS errors, network routes, firewall rules, a stopped listener, or host configuration can prevent the sender from connecting. Check the provider’s delivery record and your endpoint’s DNS, network, firewall, and application availability. GitHub’s troubleshooting guide distinguishes connection errors and recommends checking network access and its current IP information; any IP allowlist should be treated as operational data that may need updating. See GitHub’s webhook troubleshooting guide.
#1 Best Overall
2. The receiver takes too long
A handler that performs database work, calls other services, or runs a lengthy job before responding can exceed the sender’s deadline. GitHub recommends a 2XX response within 10 seconds; if it does not receive one within that window, it terminates the connection and considers the delivery failed. Queue work asynchronously so the request handler can respond after durable acceptance, not after all downstream work finishes. The 10-second limit is GitHub-specific, not a universal webhook deadline. See GitHub’s webhook best practices.
3. The response is rejected
A non-2XX status or invalid HTTP response may count as a failed delivery, depending on the sender. Record the response status and correlate it with the provider’s delivery record. Do not return success until you have safely accepted or persisted the event; otherwise, a crash after the acknowledgement can leave you with no durable copy to process.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
4. Signature verification fails
Common causes include using the wrong secret, checking the wrong header or algorithm, or verifying a body that middleware has already changed. Shopify’s HTTPS HMAC verification uses the raw request body and the app’s client secret; parsing and re-serializing JSON first can invalidate the check. GitHub recommends its X-Hub-Signature-256 header, which uses HMAC-SHA256. Follow the relevant provider’s exact instructions: Shopify’s verification guide and GitHub’s best practices.
5. A delivery is repeated
Retries and network failures can result in a delivery reaching your system more than once. Shopify explicitly notes that duplicate deliveries can occur and provides delivery identifiers. Store the relevant provider event or delivery ID and make consequential business actions idempotent: handling the same event again should not create a second charge, order, or other unintended side effect. GitHub uses X-GitHub-Delivery to help identify repeated deliveries, and its redelivery uses the same value as the original.
Rank #3
An Idempotency-Key header is not a universal fix. It works only when the receiving server supports and documents it; MDN labels the header experimental and non-standard. See MDN’s Idempotency-Key reference.
6. Events arrive late or out of order
A later event can arrive before an earlier one, and a delivery can be delayed. GitHub notes that webhook deliveries may arrive in a different order from the events and may take minutes to appear. Avoid blindly applying an old event over newer state. Use provider timestamps and identifiers where appropriate, and reconcile with the provider’s authoritative API when ordering matters.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
These are common failure classes, not guarantees that every provider retries, preserves event order, or reports failures in the same way. Confirm those behaviors in the documentation for the service and transport you use.
Design a receiver that can recover
- Protect the endpoint. Use HTTPS with certificate verification enabled. Keep signing secrets high-entropy and securely stored; do not put credentials in a payload URL.
- Subscribe narrowly. Request only the event types your application needs, and check event type and action before acting.
- Verify the exact signed input. Use the provider’s specified secret, header, algorithm, and raw or canonicalized input. Never assume two providers sign the same representation.
- Persist before acknowledging. Use durable storage or a recoverable queue. Design for a process crash after the response and for a worker crash during processing.
- Make side effects retry-safe. Track provider identifiers and apply application-level idempotency to consequential operations. Do not assume a generic idempotency header is supported by the sender or receiver.
- Keep useful, limited logs. Record event and delivery identifiers, timestamps, event type, signature result, response status, and processing state. Avoid logging secrets or unnecessary sensitive payload data.
- Plan for missed deliveries. Define how operators will find failed deliveries, request redelivery where available, and reconcile missing state. GitHub recommends redelivery of missed deliveries. Shopify’s troubleshooting documentation describes recovery after extended downtime, including re-subscribing where applicable and importing missing data.
Retry-After can communicate a requested waiting period in responses such as 429 or 503, but it does not establish that every webhook sender will honor that request. Follow the provider’s retry documentation. See MDN’s Retry-After reference.
Compare provider behavior before relying on it
Before building around a webhook, check the documented behavior for the exact provider, API version, and transport you use. Shopify documents HTTPS, Amazon EventBridge, and Google Cloud Pub/Sub delivery; its HMAC verification guidance applies to HTTPS deliveries, while managed transports carry delivery metadata differently. Shopify’s current API reference documents supported mechanisms and metadata: Shopify Webhooks API reference.
| Behavior to check | Why it matters |
|---|---|
| Transport and payload envelope | Determines how to receive and parse the event, and whether an HTTPS-specific verification method applies. |
| Signature method and verification input | Identifies the header, algorithm, secret, and exact bytes or representation to verify. |
| Acknowledgement deadline | Sets how quickly the receiver must return an acceptable response. |
| Retry schedule and attempt limit | Defines how long transient failures may be retried and when automatic delivery stops. |
| Redelivery and recovery options | Shows how operators can replay missed events or reconstruct missing state. |
| Duplicate and ordering behavior | Guides deduplication and protection against stale updates. |
| Event and delivery identifiers | Provides keys for correlating logs and recognizing repeats; these may serve different purposes. |
| Version metadata | Helps identify schema changes and interpret the event against the API version that produced it. |
Provider-specific examples
- GitHub: Its documented response window is 10 seconds, and it recommends asynchronous queueing. Its
X-GitHub-Deliveryvalue helps identify repeated deliveries; redelivery uses the original value. Consult GitHub’s best practices and troubleshooting guidance. - Shopify: For HTTPS deliveries, Shopify documents a JSON POST and headers including
X-Shopify-Hmac-Sha256,X-Shopify-Webhook-Id,X-Shopify-Event-Id, andX-Shopify-API-Version. If Shopify receives no response or an error, it documents eight retry attempts over the next four hours; its troubleshooting documentation says delivery stops after eight failed attempts. These figures describe Shopify’s documented behavior, not a general webhook rule. Check delivery structure, verification, and troubleshooting for the current details.
When should you use webhooks?
Use webhooks when your application needs event-driven notification without repeatedly polling a service. They can reduce unnecessary checks and provide timely updates, but they are not a substitute for a reliable recovery plan. Your receiver must handle transient failures, duplicate and delayed events, and provider-specific delivery rules. If missing an event would leave important state incorrect, pair delivery handling with reconciliation against the provider’s authoritative data.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches
