Make webhook effects safe to repeat
Design an event-processing record that survives retries and worker crashes. Test concurrent delivery, durable acceptance, and downstream side effects.
Webhook idempotency means that repeated processing does not repeat an effect that should happen once. A cache entry marked seen is not enough if the worker can crash between recording that entry and completing the work. Start with the concrete effect: creating an entitlement, sending a notification, or recording a payment transition.
GitHub documents delivery identifiers and redelivery behavior. The identifier semantics differ by provider. Build a processing key from the verified provider context and the appropriate event or delivery identity.
Keep a durable event disposition
The following is a suggested state record for a synthetic provisioning handler. Choose transaction and queue mechanisms that fit your storage system. Authenticate the message before it can enter this record.
| State | Meaning | Retry behavior |
|---|---|---|
| Accepted | Verified input stored durably | Resume or enqueue the pending work |
| Processing | A worker holds bounded responsibility | Recover after lease or worker failure |
| Completed | Intended effect and result recorded | Return the previous disposition |
| Needs review | Outcome cannot be determined safely | Reconcile before repeating the effect |
Use a uniqueness constraint or equivalent atomic operation for the processing key. A read-then-insert sequence can admit two workers at the same time.
Test the failure between each step
Send two controlled deliveries concurrently. Confirm one logical effect, not merely one successful HTTP response. Interrupt a test worker after durable acceptance, after the business write, and before completion is recorded. Then replay the event and inspect the resulting state.
When a database change and an external call cannot share a transaction, define the recovery mechanism explicitly. An outbox, provider idempotency key, or reconciliation operation may be appropriate. Do not claim exactly-once behavior when an uncertain external result can still be repeated.
Decide what acknowledgement proves
A success response should mean the event reached the durability point required by your design. It need not mean every asynchronous effect is complete. Record that distinction so operations staff do not treat an accepted delivery as finished work.
Keep event retention aligned with supported redelivery and reconciliation procedures. Define how payload changes under an existing identity are rejected or investigated. Preserve a bounded audit record without storing secrets unnecessarily. The final regression should cover duplicate arrival, simultaneous workers, crash recovery, and the legitimate first event, with the business effect checked in each case.
Find the gaps before your next launch
Use the release checklist to identify changed security boundaries and missing evidence. Discuss the application paths you want reviewed before launch.