What are webhooks?
Webhooks let a system send event data to a configured endpoint instead of waiting for another application to ask whether something changed. GitHub's documentation describes subscriptions that cause an HTTP request when a relevant event occurs.
For a SaaS example, an export service might notify BriefRelay that a customer's export completed. BriefRelay's receiver checks the delivery, associates it with the permitted workspace and job, and arranges the intended follow-up work.
A webhook is not the opposite of an API. It is an event-delivery pattern commonly implemented through HTTP endpoints. A broader API integration may combine event notifications with direct reads and reconciliation.
Download the local receiver exercise and checklist
The original Node.js lab models a fictional export.completed event with six fields, a bound workspace, accepted-event records, a queue, and a completion-notification effect. The checklist records the provider and storage decisions a real receiver needs.
Run node saas-webhook-receiver-lab.mjs with Node.js 22 or later. It shows an accepted event, a duplicate receipt, a simulated worker retry, one applied effect, and a second distinct event whose logical effect was already applied.
The exercise performs no network request, file write, HTTP acknowledgment, export, or actual notification. Its records exist only in memory and disappear on restart. Its public fixture key is teaching data, not a credential for a real endpoint.
Separate receipt, queued work, and the business effect
A receiver first decides whether to accept the delivery. A worker later performs the intended business operation. Those events can happen at different times and have different failure modes.
In a production design, choose an acknowledgment point that reflects the actual storage guarantee. If accepted work must survive a process failure, a memory-only queue is insufficient. Coordinate receipt and work creation through the database or queue contract your system actually provides.
GitHub currently documents a ten-second response window and suggests asynchronous processing to keep receipt handling timely. Other providers can have different deadlines and retry behavior. Check the actual subscribed event and provider documentation.
The conceptual diagram shows that design sequence. The downloadable lab models its decisions synchronously in memory; it does not implement the durable store or send the acknowledgment shown in a real receiver design.
Verify the original delivery before trusting its fields
Use the provider's documented signature scheme and maintained tooling. GitHub, for example, documents HMAC-SHA256 over the payload contents, an X-Hub-Signature-256 header, and a timing-safe comparison. Those details are specific to that contract.
The local exercise uses a fictional sha256= envelope over a raw Buffer. Altering whitespace or a Unicode representation changes those bytes and invalidates the existing signature. Verification happens before JSON parsing and dispatch.
A valid signature does not establish that every payload belongs to the intended customer or supported operation. The lab then checks the six-field schema, issuer, event type, version, bound workspace, and allowed job.
Timestamp checks, replay protection, key rotation, and library behavior depend on the provider. The lab does not implement those production mechanisms. Keep the real signing key in the approved server-side store and use a public fictional fixture only for this local demonstration.
Use the right identity for duplicate deliveries
The fictional receipt key combines issuer, workspace, and event ID. Receiving the same accepted event again returns duplicate without creating another queued job. A contradictory reuse of that identity returns conflict rather than silently replacing the earlier meaning.
After verification, the exercise fingerprints the known semantic fields in a fixed order. A newly signed pretty-printed version of the same event remains a semantic duplicate. A modified body with the old signature fails earlier at verification.
Read the provider's definition of event and delivery identity. GitHub documents that its delivery identifier remains the same for a requested redelivery. Do not assume another provider uses the same header, event lifecycle, or identity rules.
Define how conflicts are investigated and reconciled. Overwriting an accepted event's meaning can hide a source error, an integration mismatch, or a receiver assumption that needs review.
| Input or state | Decision | Local effect |
|---|---|---|
| First valid scoped event | accepted | One pending job |
| Same accepted event again | duplicate | No additional job |
| Same identity with a different allowed job | conflict | Existing meaning remains |
| Invalid signature or contract | rejected | No accepted event |
| Simulated failure before worker commit | retry | Job remains pending |
| Distinct event for an applied logical completion | already-applied | No second notification effect |
Make the business operation safe to repeat
Delivery deduplication and business-operation identity solve different problems. Two distinct event IDs might still describe the same logical completion. The exercise therefore has a second key: workspace, job ID, and completion-notification action.
After the first local completion, a second accepted event for that job can finish its queue record without adding another notification effect. This illustrates the relationship between event receipt and the intended side effect.
A real external effect needs its own design. A database record updated once does not automatically prevent an external message from being sent twice if the process fails between those steps. Examine the actual transaction, provider idempotency support, or outbox/reconciliation mechanism.
The background-task guide explores repetition and side effects. Keep retry policy bounded and distinguish recoverable work from a terminal failure that needs an owner.
Plan missed events, ordering, and reconciliation
Do not assume notifications arrive in the order your business process expects, or that every failed delivery will be retried automatically. Record the provider's actual delivery, retention, retry, and redelivery behavior.
A reconciliation process can compare accepted local state with the authoritative source and identify missed or unresolved work. Its cadence and access need to fit the business tolerance for stale data and the provider's limits.
The Stripe subscription guide retains billing-specific state and access decisions. The Resend guide retains message-event semantics. A general receiver should not reuse one provider's event meanings as a universal rule.
Keep support visibility focused on identifiers, processing status, attempts, and permitted evidence. Retaining complete private payloads everywhere can make troubleshooting harder to govern without improving the decision.
What the lab verifies and where it stops
The signature function was checked against GitHub's published Hello, World! validation vector. Additional tests cover altered bytes, malformed signatures, unsupported fields and versions, foreign workspace and job data, duplicate and conflicting receipts, and a simulated worker failure.
Tests also confirm that two distinct events for the same logical completion produce one local effect. Restarting the receiver deliberately resets all history and allows the event again, demonstrating the limit of memory-only records.
No live server, durable queue, concurrent worker, provider callback, key rotation, or actual external side effect was tested. Use the exercise to understand the decisions, then verify a maintained integration and real storage design for the application.
Sources and original exercise checked October 28, 2026. A reliable webhook workflow connects authenticated delivery to scoped, recoverable business work rather than treating a received HTTP request as completed processing.