What is Webhooks?
Webhooks are event-triggered HTTP notifications sent from one system to a URL configured in another. Instead of repeatedly asking whether something has changed, the receiving system waits for a request when a subscribed event occurs. A typical webhook sends an HTTP POST containing event data, often as JSON.
A webhook is a notification mechanism, not a guarantee that the receiving application has completed its work. Delivery can fail, be repeated or arrive later than another event. Reliable integration therefore depends on authenticating the request, accepting it safely and making the resulting action resilient to retries and failures.
The Techie Broadband terminology guide connects webhooks with APIs, networking and application infrastructure. This guide follows an event from the source to the receiver, then explains what can break at each stage.
How a webhook works
The source system publishes events, such as a completed build or updated record. A subscription specifies the events of interest and the destination endpoint. When a matching event occurs, the source sends a request to that endpoint. The receiver checks the delivery, accepts or rejects it, and performs the relevant work.
For example, a repository event could trigger a build pipeline. The notification starts an integration workflow; it does not establish that a build passed or that a deployment succeeded. Those outcomes need their own records.
Configure the subscription, destination and authentication mechanism.
A matching event occurs in the source system.
The source creates an HTTP delivery attempt.
The receiver validates the request and its expected event format.
The receiver accepts responsibility or reports a failure.
Application work proceeds, with completion monitored separately.
The request travels from source to receiver. Its HTTP response travels back to the source. That response can confirm receipt or acceptance according to the provider's contract, but it is not a separate event sent to every downstream system.
The infographic separates notification, verification, durable acceptance and processing. Keeping those boundaries clear helps prevent a delivery log from being mistaken for proof that the intended action happened.
Webhooks, APIs, polling and WebSockets
A webhook often interacts with an API rather than replacing it. A small event notification may identify a changed object, after which the receiver uses the source's API to retrieve the information it needs. A richer payload may include a snapshot of object data.
Mechanism | Who initiates the useful exchange? | Main consideration |
|---|---|---|
Ordinary API request | The system asking for data or an action | It must decide when to ask |
Polling | A client repeats requests on a schedule | Requests continue when nothing changes |
Webhook | The event source sends a notification | The destination must handle delivery uncertainty |
WebSocket | Applications exchange messages over an established connection | Connection lifecycle and application message semantics matter |
Message broker | Producers and consumers use a messaging service | Persistence and delivery guarantees depend on the broker and configuration |
Calling a webhook a reverse API can be a useful shorthand, but it is not a separate universal wire protocol. Headers, payloads, signatures, timeout limits and retry policies differ between providers. A normal webhook does not require a persistent WebSocket connection.
Techie Broadband calculation: polling versus notifications
Assume one monitored resource is polled once per minute for 30 days. That produces 30 x 24 x 60 = 43,200 polling requests. If instead there are 200 relevant events per day and exactly one initial delivery per event, there are 6,000 webhook requests.
The illustrative reduction in notification-related requests is 86.1%. This excludes registration, retries, API fetches, reconciliation and differences in payload size. It is not a measured saving, a universal efficiency claim or a prediction of lower bills. Polling can still be appropriate when events are unavailable or occasional checks meet the need.
Under a separate simplified assumption that changes occur uniformly between successful one-minute polls, the mean wait to the next poll is 30 seconds. A webhook avoids that particular scheduled wait, but still has source, delivery, network and processing delays. Near real time does not mean instant.
What is in a webhook request?
An endpoint typically receives a method, URL path, headers and a body. The body can contain an event identifier, event type, timestamp and object information, but their exact meaning depends on the source. Do not assume every webhook contains the full current object or the same identifier scheme.
Item | Useful question |
|---|---|
Subscription | Which events and account does this integration cover? |
Endpoint path | Which handler is supposed to receive the request? |
Event identifier | Does it identify a source event, a delivery or an attempt? |
Event type | Which permitted handler should run? |
Signature or credential | What exactly does the provider authenticate? |
API/schema version | Which payload structure must the receiver understand? |
Object data | Is this a snapshot, a reference or a partial representation? |
An event ID and an object ID are different things. Two updates to the same object can be two legitimate events. Conversely, the same event can be delivered more than once. Deduplicating every message with the same object ID can discard changes you needed to process.
Keep parsing tolerant of additive fields while validating the fields required by your handler. Explicitly handle unsupported event types and versions. A payload that is valid JSON can still be invalid for the intended operation.
Verify the delivery before trusting its contents
HTTPS protects traffic in transit and lets the sender authenticate the receiving server's certificate. It does not, by itself, prove that an incoming POST came from the webhook provider. The receiver needs the provider's documented authentication mechanism.
HMAC signatures are common. With this approach, the provider and receiver share a secret and compute a message authentication code over defined data. The receiver checks that value using a suitable constant-time comparison. Other providers may use different credentials or signature schemes; follow the actual contract rather than copying another service's handler.
GitHub's webhook validation documentation describes HMAC-SHA256 over the original request body, supplied in X-Hub-Signature-256. Capture those bytes before a framework parses and re-serialises the JSON. Whitespace changes can alter the signature even when the parsed data means the same thing.
A valid signature does not automatically prove freshness. A captured valid request can be replayed. Check authenticated timestamps and event identifiers where the provider's scheme supplies them, apply its recommended tolerance and retain appropriate processing records. Do not assume arbitrary headers are covered by a signature over the body alone.
Techie Broadband local experiment: identical data, different bytes
We ran a local Python experiment using a made-up demonstration secret and this invented payload:
{"id":"demo-001","type":"build.completed"}
The test calculated an HMAC-SHA256 signature, verified the original bytes, then parsed and re-serialised the same object with indentation. Python's constant-time comparison accepted the original body and rejected the altered representation.
Local check | Result |
|---|---|
Original body with matching signature | Accepted |
Parsed values after re-serialisation | Still equal |
Re-serialised bytes with original signature | Rejected |
This verifies the byte-level distinction in the local experiment. It is not a live GitHub integration, a full endpoint implementation or evidence that a production service is secure. Provider verification libraries help handle their exact format, including rotation and timestamp rules where applicable.
Acknowledge promptly, but keep the promise you make
A useful receiver verifies a request, records it durably and hands work to a background processor where appropriate. That keeps the source's HTTP request short without losing responsibility for the event. Returning success before the only copy exists in durable storage creates a loss window if the process crashes.
GitHub.com's current best-practice guidance requires a 2xx response within 10 seconds. That is a GitHub.com rule, not a universal webhook timeout; other products and versions can differ. Check your sender's exact acceptance criteria.
HTTP 202 means accepted for processing, not completed. Its meaning also does not guarantee that every webhook provider accepts it as a successful delivery. Use a response allowed by the provider, and track worker completion separately from HTTP acknowledgement.
Boundary | Evidence to record | What it does not prove |
|---|---|---|
Source event exists | Source event record | A request reached your infrastructure |
Delivery attempted | Attempt time and destination | The receiver accepted responsibility |
Receiver accepted | Durable inbox record and response | The business action completed |
Worker completed | Result and operation identifier | Every other integration is up to date |
A queue is only as durable as its configuration. Recording an event in memory and calling it queued does not make it recoverable after restart. Define what happens when the database or queue is unavailable before returning an acknowledgement.
Retry policies differ between providers
Webhooks do not all automatically retry. GitHub's failed-delivery guidance states that failed deliveries are not automatically redelivered. Recovery can involve manual redelivery or your own automation.
By contrast, Stripe's webhook documentation, checked in October 2026, describes automatic retries for up to three days with exponential backoff in live mode. Sandbox behaviour differs. Stripe also does not guarantee event delivery order. These are service-specific statements, not properties of every webhook.
An ambiguous timeout can produce a duplicate: the receiver records an event, but its response is lost. The source cannot tell whether acceptance happened and may try again. That is why a network failure must not automatically mean repeat the business action without checking.
Record the provider's retry window and timeout policy.
Identify how to inspect and redeliver failed deliveries.
Distinguish source redelivery from retries inside your own worker.
Keep repeatedly failing work visible rather than looping indefinitely.
Plan reconciliation for changes missed beyond the retention window.
For a confirmed delivery that your worker accepted but could not process, retrying the internal job is usually a different operation from asking the provider to resend everything. Keep those responsibilities explicit.
Make repeated events safe to process
Idempotency means repeating an operation has the same intended effect as doing it once. It is particularly important for provisioning access, creating records, triggering builds and other actions that should not repeat merely because a delivery was retried.
A persistent inbox can use a unique key scoped to the provider or subscription and the stable event identifier. An atomic insert prevents concurrent handlers from both accepting the same key as new. A check-then-insert sequence without suitable transaction or uniqueness protection can race.
Techie Broadband local experiment: five attempts, two actions
Our second local experiment submitted demonstration IDs in this order: demo-001, demo-001, demo-002, demo-001, demo-002. A SQLite inbox enforced a unique source/event pair. New inbox rows and simulated action rows were written in the same transaction.
The result was two new events, three duplicate attempts and two simulated actions. Closing and reopening the database retained the two action records. This tests local uniqueness and persistence; it does not establish exactly-once processing across an external API, network service or production crash scenario.
Attempt | Event ID | Simulated action |
|---|---|---|
1 | demo-001 | Recorded |
2 | demo-001 | Duplicate skipped |
3 | demo-002 | Recorded |
4 | demo-001 | Duplicate skipped |
5 | demo-002 | Duplicate skipped |
The harder boundary is an external side effect. A worker might call another system successfully and crash before recording completion locally. On restart, repeating that call can create a duplicate. Use the downstream service's idempotency support where available, a stable operation key and a recovery design that handles that uncertainty. A processed flag in your own database cannot alone prove what another system did.
Choose deduplication retention deliberately. It must cover the relevant redelivery and recovery period. An unauthenticated attacker-supplied identifier should not reserve legitimate event keys before verification. Likewise, a mutable unsigned header is not a complete business-level replay defence.
Out-of-order events and missed changes
Do not infer causal order from arrival order. An earlier event can be delayed while a later one succeeds. A timestamp may have limited resolution, and different events can share it. A retry can bring old data back after a more recent update.
Decide what the handler needs: a current-state view, an audit of every transition or a particular business action. Those goals require different processing rules. For current-state synchronisation, an event can trigger a fresh authorised API read. For transition-sensitive work, use the source's documented version or sequence model where available.
Reconciliation checks the actual source against the receiver's stored state to detect gaps. It complements webhooks rather than proving notifications are unnecessary. A receiver that was offline longer than the provider's retry window may need more than redelivery of the last failed attempt.
Receiving webhooks in a UK home lab
The destination must be reachable from the sender, not merely from your laptop. The sender's localhost refers to its own machine; it cannot reach your local service simply because you registered a loopback address.
A reverse proxy, hosted relay or suitably configured tunnel can provide an ingress path to a private receiver. Decide which component verifies the request, preserves the original body and accepts responsibility. A public URL alone does not establish end-to-end delivery.
For direct home hosting, assess public address reachability, CGNAT, IPv4 or IPv6 support, firewall rules, certificates, changing addresses and service uptime. Do not assume that an IPv6 endpoint is supported by every provider's delivery system. A tunnel that starts an outbound connection may avoid a direct inbound mapping, but adds another dependency.
A typical event payload is small enough that headline broadband download speed is rarely the whole explanation for a late event. Source scheduling, DNS, TLS setup, route latency, queueing and worker performance can dominate. Large payloads or burst traffic change that balance, so measure the actual path.
Techie Broadband queue model: accepted can still mean waiting
Assume 12,000 valid events arrive evenly over 60 seconds, or 200 per second. The workers complete 150 per second, processing immediately from an initially empty queue. With no failures or other limits, they complete 9,000 during that minute and leave 3,000 waiting.
If arrivals then stop, clearing the remaining queue takes another 20 seconds. HTTP acknowledgements can all be quick while completion is still delayed. If 200 events per second continues indefinitely, the queue grows by 50 per second; buying more ingress capacity does not fix insufficient processing capacity.
These are deterministic arithmetic assumptions, not a measured system or a latency guarantee. Record queue age as well as queue depth: the age of the oldest pending event often explains the reader's actual problem better than a successful-delivery percentage.
Secure both the receiver and the publisher
For the receiver, restrict accepted methods and payload sizes, validate the expected event schema and protect downstream operations from untrusted fields. Keep secrets outside URLs and redact credentials and sensitive payload data from logs. Rate limits must consider legitimate bursts and retries as well as abuse.
If a framework's browser-oriented CSRF check blocks legitimate server callbacks, use its documented integration approach for that specific route while retaining webhook authentication. Do not disable protections across the whole application as a shortcut.
For a publisher that accepts user-configured callback URLs, outbound requests create a server-side request forgery risk. Validate permitted schemes and destinations and enforce appropriate network restrictions at connection time, including after DNS resolution or redirects where supported. Otherwise, a callback feature can be used to reach internal services rather than the intended external subscriber.
Secret rotation, clock accuracy and replay protection are part of the provider-specific design. Do not invent a universal timestamp header or assume one provider's signature format will validate another's requests.
Troubleshoot the last proven boundary
Confirm a qualifying source event occurred and the subscription covers its account and type. A missing event is different from a failed HTTP delivery.
Inspect the source's delivery log. Record the destination, attempt ID, response status and timing; check whether automatic retries exist.
Check DNS, reachability, certificate validation and the endpoint's exact path. A browser GET response does not prove that the required POST handler works.
Check ingress logs and proxy routing. Identify whether the request reached the proxy, application or neither. Watch for redirects and interactive login challenges.
Verify the signature against the original bytes, correct secret and expected environment. Check which component parsed or changed the body.
Inspect durable acceptance. A 2xx response with no inbox record needs a different investigation from an accepted job that is still pending.
Trace the worker result and downstream operation key. Check duplicate handling, schema errors, ordering assumptions and repeated failures.
Recover using the provider's supported redelivery or reconciliation process, then confirm the intended action once. Do not declare recovery solely because the HTTP status is green.
Symptom | Likely boundary to investigate |
|---|---|
No delivery attempt | Event subscription, source event or provider limits |
Connection or TLS failure | DNS, route, firewall, certificate or service availability |
3xx response | Wrong endpoint or a redirect the sender may reject |
401 or 403 | Authentication, policy or signature validation |
Signature fails after parsing | Original-body capture and exact verification scheme |
2xx but no action | Durable inbox, queue, worker or downstream operation |
Action runs twice | Deduplication key, race or external side-effect recovery |
Older state overwrites newer state | Event ordering and state-update rules |
Webhooks questions answered
Are webhooks the same as APIs?
No. A webhook is an event-triggered notification to a configured endpoint. An API provides an interface for data or actions. A webhook handler can use an API to retrieve current data or perform the resulting work.
Do webhooks guarantee real-time delivery?
No. They avoid scheduled polling waits but still depend on source behaviour, network delivery and receiver processing. Delay, failure, retries and queueing remain possible.
Does a 200 response mean the task is complete?
Only if the endpoint's contract actually defines it that way. Many receivers acknowledge accepted work before a background worker finishes. Record the completed action separately from delivery acceptance.
Do all providers retry failed webhooks?
No. Retry rules differ. GitHub does not automatically redeliver failed deliveries, while Stripe documents live-mode retries under its own policy. Check the exact provider and environment.
Can I receive webhooks behind CGNAT?
A directly reachable inbound IPv4 service may be unavailable, but a suitable hosted receiver or outbound-connected relay can provide an alternative ingress path. Verify the full route, authentication and acceptance responsibilities.
Why does a signature fail when the JSON looks correct?
A signature may authenticate exact bytes rather than the parsed meaning. Re-serialisation, whitespace changes, the wrong secret or a different signature format can cause failure. Capture and verify the provider's original signed input.
Key takeaway
Webhooks connect an event to a notification, then an application connects that notification to an outcome. Keep the evidence for each stage separate. Reliable operation comes from verified requests, durable acceptance, safe repeated processing and a recovery plan for missed or ambiguous deliveries.
