Estimated reading time : 3 min · Published October 1, 2026
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.
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.
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.