A webhook lets one system notify another that something happened. The business value is often immediate: a payment updates an order, a booking triggers preparation or a completed job starts the next workflow. Reliability depends on what happens when messages arrive twice, arrive late or fail partway through processing. Those conditions belong in the original design, even for a small integration with modest traffic.
Translate the event into one business outcome
Imagine a Sydney training provider receiving a payment event and enrolling the customer in a course. The required outcome is one enrolment attached to the correct purchase. Receiving the message twice should not create a second enrolment or send contradictory confirmations. Stripe's webhook guidance explicitly addresses duplicate events and warns that event ordering is not guaranteed. Use the event identifier and business record identifiers deliberately, and decide how the integration recognises work already completed. The right duplicate rule may depend on the provider's event model.
Record receipt separately from completion
A system can receive an event successfully while the downstream business action remains unfinished. Keep those stages distinct. For example, record that the message arrived, validate it, place the work in a queue and mark the enrolment complete only after the relevant changes succeed. Verify the sender using the provider's documented mechanism. Give operations staff a view of pending and failed work, with a recognisable order or customer reference. A green delivery status from the sender alone should not be mistaken for evidence that every downstream task finished.
Make replay a controlled action
When a temporary fault is fixed, staff may need to retry the failed work. A replay should preserve the original event context and avoid repeating actions already completed. Consider the difficult case where enrolment succeeded but the confirmation email failed. Replaying the whole workflow should not blindly create a fresh enrolment. Set a retry policy with a stopping point and an escalation route. Preserve enough diagnostic information to explain the failure, while avoiding unnecessary customer information in technical logs or staff-facing error messages.
Demonstrate the awkward cases
Ask the delivery team to show the same event arriving twice, a later event arriving first and a failure between two downstream steps. Observe both the records and the staff-facing queue. Document:
- The identifier used to detect repeat processing.
- The point at which receipt is acknowledged to the sender.
- Who sees exhausted retries and how they safely replay work.
- How the business checks that every expected outcome eventually happened.