1
Verify
Check the signature and the timestamp. Reject with
401 if either fails. See Verify
signatures.2
De-duplicate
Record the event
id. If you have seen it, answer 200 and stop.3
Acknowledge
Answer
2xx straight away.4
Work
Do the slow part, such as updating orders or sending email, in a background job.
Webhook idempotency
De-duplicate on the eventid. It is identical on every retry of the same event.
The safe way is a unique constraint, so the check and the write are one atomic step:
A second guard: the transaction itself
An event id check does not cover everything. An event resent through the API has a new id, and an endpoint you register twice receives the same transaction under two ids. So make the business action idempotent too. Key it on the transaction’s public id and the outcome:Respond fast, process later
Answer within a few seconds. Payve waits up to 30 seconds, then counts the attempt as failed and retries, which produces the duplicates you are trying to avoid. If your queue or database is down, answer500 or 503 so that Payve retries. Do not answer 200 for an event you failed to store.
Branch on the event type
Decide what to do fromtype. Do not decide from data.status: that field holds the transaction’s detailed internal state, which has more values than the four statuses the API returns.
Always answer
2xx to an event type you do not recognise. Answering 4xx stops retries and shows
as a failed delivery.Confirm before you release value
For anything that hands over goods or money, fetch the transaction and act on what the API says now.Events can arrive out of order
Network retries mean a later event can reach you before an earlier one. Never assume order. Use the transaction’s current state from aGET when order matters.
Checklist
- The signature is verified against the raw body.
- Deliveries with a timestamp more than five minutes off are rejected.
- The event
idis stored under a unique constraint. - The business action is idempotent on the transaction’s public id.
- The handler answers
2xxin under five seconds. - Storage failures answer
5xx, never200. - Unknown event types answer
2xx. - A scheduled job reconciles transactions that never got an event.

