Acknowledge first, work afterwards
Answer2xx as soon as you have the payload, then queue the work. Your endpoint has 30 seconds, and a handler that does its processing inline is a handler whose latency is your database’s latency.
The shape that works: verify the signature, write the event to your own queue or table, answer 2xx, process from there.
Make processing idempotent
Design so that handling the same event twice changes nothing the second time. Key onevent_id, which a retry and a replay re-send unchanged, and record what you have already handled. A refund sent under a deprecated name carries its own event_id, so key refunds on deposit_id. See Deprecated deposit events.
Do this even where you believe an event arrives once. The failure it prevents is paying someone twice.
Treat the event as a signal, not as the truth
The payload tells you something changed. When the decision matters — releasing goods, paying someone, telling a customer their money arrived — read the resource back and act on what it says now. An event describes a moment. The resource describes the present, and by the time you process a queued event those can differ.Never trust an unverified payload
Check the signature before you read a single field. An endpoint that acts on the body first and verifies later has already acted. See Validate signatures.Ignore what you do not recognise
Answer2xx to an event name you do not handle, and log it. New events are added over time, and a handler that throws on an unfamiliar name turns an addition into an outage.
Answering a 4xx other than 408 or 429 discards the event for good. When a delivery fails lists what is retried.
The same goes for unfamiliar fields inside a payload you do handle.