A correct webhook handler does four things, in this order: verify, de-duplicate, acknowledge, then work.
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

Treat every delivery as at-least-once. The same event can arrive twice: when your 200 is lost on the network, when a retry crosses with a slow first attempt, or when someone retries it by hand. If your handler credits a customer each time it runs, a duplicate credits them twice.
De-duplicate on the event id. 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:
Do not check with a SELECT and then INSERT. Two copies of the same event arriving together both pass the SELECT. Let the database’s unique constraint decide.

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.
Do only three things before you answer: verify, store the event id, and put the event on a queue. Everything else belongs in a worker.
If your queue or database is down, answer 500 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 from type. 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.
A payin.successful event is also sent for a payment link that was overpaid or underpaid. An underpaid payment credits nothing to your wallet. Check subStatus on the pay-in before you fulfil an order.

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 a GET 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 id is stored under a unique constraint.
  • The business action is idempotent on the transaction’s public id.
  • The handler answers 2xx in under five seconds.
  • Storage failures answer 5xx, never 200.
  • Unknown event types answer 2xx.
  • A scheduled job reconciles transactions that never got an event.