Quick answer
A webhook receiver must authenticate each delivery under the sender’s contract, validate the event and durably record accepted work so it can be recovered. It must then recognize duplicates and apply the business operation idempotently. Receiving a POST or returning success does not prove that an event is legitimate or that its effect is complete.
Webhooks connect systems without requiring one to poll the other continuously. That convenience creates a responsibility: a public URL may receive forged, delayed, repeated or out-of-order messages. The design must explain how each delivery crosses the trust boundary and how the team recovers from failures without improperly repeating an action.
- Authenticate delivery
- Validate and record the event
- Process idempotently
- Monitor and recover
Start with a specific sender’s contract
List the events your application needs, the endpoint to be called and the responses the sender accepts. Check format, version, authentication, response deadlines and redelivery behavior. Header names, algorithms and intervals must not be treated as universal standards across providers.
For example, GitHub documents signatures in X-Hub-Signature-256 and a delivery identifier in X-GitHub-Delivery. Stripe has its own signing contract and requires attention to the original request body. These examples show why the first step is to read the chosen integration’s documentation rather than copy a generic receiver and change only the URL.
HTTPS and signatures serve complementary roles
HTTPS protects communication in transit. Signature validation specified by the sender helps the application verify message origin and integrity. Keep the secret on the server in protected configuration, out of repositories, browsers and URLs that may appear in logs.
Prefer the official verification library when available and suitable for the version in use. If implementing verification yourself, follow the documented algorithm, format and secure comparison method exactly. An improvised comparison or incorrect data conversion can undermine protection even when the header looks correct.
Preserve the data required for verification
Some contracts compute the signature over the received body’s bytes. In Stripe’s documented case, modifying the body before verification can make validation fail. A parser, JSON reserialization or character processing can turn a semantically equivalent message into different bytes.
Define where the framework captures the original body and where verification occurs. Then validate input structure and limits for the expected event. Do not log the secret or full payload to troubleshoot a signature problem; use a controlled reproduction with test data and minimized records.
A valid signature does not replace business authorization
After verifying the delivery, check its type, action and structure. Accept only what the integration uses, and associate references with the correct account, project or resource in your system. An authentic message can concern something that must not trigger that action in the application.
When the contract requires it or the design needs current confirmation, retrieve the resource through the provider’s authorized API. Distinguish the status reported by the event from the status the business rule needs to confirm. The application must decide which transitions are allowed, including when a notification arrives after a newer change.
Acknowledge receipt after recoverable acceptance
The endpoint must respond within the sender’s requirements, but that response must reflect what was actually accepted. If the application reports success and crashes before recording the work, it may lose the opportunity to process a delivery the sender considers complete. Define a persistence point and a way to resume the work.
One architectural option is to persist the event or a sufficient reference in durable storage and separate heavy processing. If both a database and queue are involved, examine the gap between writing and publishing: operations in different systems are not automatically atomic. Document how pending work is found and recovered after an interruption.
Delivery deduplication and effect idempotency are different
A delivery identifier can help recognize redelivery of the same message. A business operation may need its own stable key: different events can refer to the same resource and effect. An identifier alone does not establish that a task ran exactly once.
As a hypothetical example, an event starts report generation. The result is saved, but the worker’s acknowledgement is lost. On retry, the system must recognize the valid result or resume safely. For an external effect, the strategy also depends on the destination’s contract. An in-memory variable does not provide the same recovery as persistent state.
Concurrent duplicates require storage-level coordination
Two requests may arrive almost together. If both check first and only later record that the event was seen, both may conclude that they can start the action. Claiming an operation requires an exclusion mechanism suited to the database and application design.
Define clear transitions between states such as received, processing, completed and failed. Distinguish a completed operation from one that was merely claimed and abandoned after a failure. Recovery must know when work can resume without allowing two workers to produce the same effect simultaneously. An indefinite lock or forgotten key must not turn into permanently lost work.
Plan redelivery and ordering without assuming guarantees
Check whether the provider retries automatically, how it exposes failed deliveries and what happens when you request redelivery. Do not rely on an ordering guarantee that does not exist. Stripe documentation says to handle duplicates and not assume event ordering; other services have their own conditions.
GitHub documentation states that redelivery of the same event retains its X-GitHub-Delivery identifier. That detail can help test deduplication for that contract, but must not be generalized to every sender. Keep relevant references and define a recovery procedure that checks recorded state before repeating an action.
Observe the event path with minimized data
Record time, sender, type, delivery identifier when available, internal reference, validation result and work state. Correlate these with HTTP status and duration. That distinguishes signature rejection, invalid input, unavailability and failures after receipt.
Limit log retention and access. Payloads can contain customer data or information that need not remain in logs. Useful alerts identify persistent failures, old pending work or an unexpected rise in duplicates, with a known response for the team. Counting HTTP200 responses alone does not show whether operations finished correctly.
Test interruptions that demonstrate expected behavior
Use an authorized environment and test events without unintended real-world effects. Compare results with the sender’s documented contract and the application rule. The rehearsal must exercise authentication, duplication and recovery boundaries, not merely display a success response.
Record expected behavior for each case and the test’s limitations. A reliable implementation explains why a delivery was accepted or rejected and how pending work will be handled. That provides better evidence than claiming the system never duplicates events.
| Test case | Expected result | What to verify |
|---|---|---|
| Invalid signature | Rejection under the contract | No business effect |
| The same event redelivered | Duplicate recognized | Previously recorded state and effect |
| Two concurrent deliveries | Controlled operation claim | Storage protection |
| Failure after acceptance | Recoverable work | Persistent record and recovery |
| Out-of-order event | Authorized transition | Rule and current status of the resource |
How WordPane helps operate the receiver
On WordPane, logs and metrics help relate endpoint failures to the application and server usage. Git deployment tools and compatible test environments help organize versions and validate changes before they affect the public integration. Confirm the runtime, processes and project requirements in the chosen environment.
For background processing, verify the commands, process management and dependencies actually available in scope. Backups to external storage must include the data and configuration needed for recovery. Infrastructure does not automatically implement signatures, deduplication or business rules: those protections belong in the integration code. Bring the flow, event volume, peaks and recovery requirements to the briefing to assess capacity and responsibilities.
Plan infrastructure for your integrations
Describe senders, event volume, runtime and recovery to assess the environment for your receiver and its associated processes.
Evaluate my integration with WordPaneConsult panel documentation
