Estimated reading time : 6 min · Published
Write the event contract
Document the producer, expected event types, required fields and triggered operation. Describe results for creation, change and deletion where applicable. A notification should not implicitly authorise every possible action.
Choose a tracking identifier and an authoritative source to consult when uncertain. Describe how failures at the producer or receiver are detected. Integration documentation holds rules and owners; secrets belong in the project’s secure mechanism.
In n8n, test and production webhook URLs serve different purposes. Listening for a test event does not prepare ongoing reception: the production URL is registered when the workflow is published. Check the URL configured at the sender and review production runs in Executions.
The response mode changes what an acknowledgement means. With Immediately, the response reports workflow startup; it does not confirm that an order or customer record was updated. Link the event identifier, execution and final state in the destination before reporting business success.
Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.
| Checkpoint | Possible observation | Expected evidence |
|---|---|---|
| Test URL | Event visible while listening for a test | URL and environment used for the trial |
| Production URL | Published workflow and recorded execution | Execution identifier linked to the received event |
| Immediately response | The workflow started | Final state and expected operation in the destination service |
Verify before triggering an operation
GitHub documents delivery signature validation using the configured secret and received payload. Follow the actual provider’s documented mechanism; headers, algorithms and formats should not be copied from another service by analogy.
Separate origin verification, schema validation and operation authorisation. Test altered content, an unexpected event type and a missing field. Business processing should begin only after the controls required for the use case.
Plan repeats and interruptions
Define idempotent handling: a recognised repeated delivery should not create two orders or two final notifications. Test repetition before, during and after processing and an interruption between steps. The mechanism depends on the operation and storage involved.
Check the provider’s ordering and redelivery guarantees rather than assuming immediate, one-time arrival. Keep a queue of work requiring review and a way to reconcile it with the source. A positive technical response should correspond to a defined processing state.
Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.
| Situation or setting | What it means | Useful check |
|---|---|---|
| The same event arrives twice | Apply one business operation under the deduplication strategy. | Keep the event identifier and check final state, not only the HTTP code. |
| Events arrive out of order | Reconstruct the useful state without assuming delivery order. | Test an update arriving before the expected notification and consult the source if needed. |
| Invalid signature | No business effect should be triggered. | Check rejection, then the ability to process a valid event after the failure. |
Arrange monitoring and recovery
Record an event identifier, state and useful error while minimising data. Define who monitors failures, how authorised events are retried and how retries avoid duplicating completed work.
Interrupt the receiver in a test environment and restore it. Check catch-up and reconcile expected business results. Deliver an event contract, test batch, processing history and recovery procedure that the team can use.
Primary documentation : GitHub : Validating webhook deliveries.
Fictional example: DEMO-E41 triggers one business write in a database. The contract groups that write and marking the event processed in the same transaction; a unique key combining producer and identifier controls concurrent processing. Test interruption before and after COMMIT. Recovery after commit finds the completed work instead of adding another effect. Recording “received” in a separate log does not provide that guarantee.
GitHub redelivery retains the X-GitHub-Delivery value, so a retry must not be treated as a new event merely because it is another attempt. Check each other producer’s behaviour separately. DEMO-E42 illustrates a different boundary: a call to an external service times out without a response. A local transaction cannot establish whether that service acted; reconcile its reference and documented retry guarantees before repeating the action.
Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.
| Test case | Established business effect | Expected recovery |
|---|---|---|
| DEMO-E41 before COMMIT, transaction rolled back | 0 committed effects | Recover using the transactional record |
| DEMO-E41 after COMMIT | 1 effect and event marked processed | Retrieve the already committed result |
| DEMO-E41 delivered again | Still 1 effect in total | Recognize the key; do not reapply the write |
| DEMO-E42: external call without a response | Unknown outcome: 0 or 1 effect possible | Reconcile with the service; avoid blind repetition |
- GitHub : Webhook Best Practices
GitHub, consulted 22 October 2026: identifier retained on redelivery. The abbreviated DEMO-E41 and DEMO-E42 events are fictional.
- PostgreSQL : Transactions
PostgreSQL, consulted 22 October 2026: database transactions; no global guarantee for an external call.
Reference documents
- Stripe : Webhooks · Source consulted
- n8n : Webhook node · Source consulted
- GitHub : Validating webhook deliveries
Content updated on
Documented reference points for this topic
| Reference | Value or syntax | Scope |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | Standard JSON permits neither comments nor trailing commas; strings use double quotes. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | The explicit offset relates local time to UTC; this example is not an appointment. |
Dates indicate when references were consulted. These facts are neither a site audit nor an overall compliance statement.
