A message arrives after a change
An order is paid, a document is signed or a course is completed: a service can notify another application itself. A webhook sends a request to a predefined address. The recipient processes the message and starts its part of the work.
Imagine a course certificate
Imagine a fictional learning platform sending an event to a certificate system after course completion. Processing starts, but the acknowledgement is lost. The platform sends the event again. Without identifier checks, the receiver may issue two documents and send two messages.
Store both receipt of the event and the certificate outcome. A repeat should resume unfinished work or return a known result, not automatically represent a new learner achievement. This is a rule about the operation's meaning, not merely networking.
Acknowledgement differs from completion
If certificate creation takes time, the receiver can first persist the task, acknowledge receipt and process it afterward. Successful delivery then means the task exists at the receiver. The user's result comes later and needs its own verification.
Show operators at least four distinct states: received, awaiting processing, completed and requiring investigation. Otherwise failure after acknowledgement remains hidden from the sender until somebody complains. Also define who owns retrying an already accepted event.
Arrival order cannot be assumed
Messages may arrive late or repeat. Stripe explicitly warns about duplicate delivery and does not guarantee event order; its rules must be checked independently for other suppliers. If cancellation arrives before creation, a handler must not blindly move state backward.
In the teaching example, a course result might be revised before document issuance. Decide whether event contents suffice or current record state must be checked before acting. The choice depends on stale-message consequences and the API's ability to retrieve current information.
A delivery address does not authenticate the sender
A publicly reachable handler can receive unrelated requests. Use the supplier's supported authenticity check; Stripe documents signature verification. Manage its secrets as operational credentials, with restricted access and a clear replacement procedure.
After authenticating origin, validate contents: supported event type, understood version and permitted state transition. Make unknown messages visible to support. Silently accepting everything creates the appearance of healthy delivery without useful action.
Test duplicates and missing events
With test data, deliver one event twice, delay the next and interrupt processing after receipt. Check that work resumes without duplicating the business result. Then reconcile sender and receiver records to establish whether completely unprocessed events can be detected.
