API ReferenceWebhooks
Webhook Best Practices
Build a resilient webhook receiver.
Respond fast — acknowledge before processing
Capture the body, persist it to a queue, and return 200 OK immediately. All business logic runs asynchronously off that queue. This decouples your processing time from Buvei's 10-second timeout.
De-duplicate on eventId
Webhooks may be delivered more than once (retries, network duplicates). Use eventId as the primary key in your processed-events table; ignore duplicates.
Verify signatures, always
Reject any webhook whose signature does not validate. See Webhook Security.
Stay tolerant to out-of-order events
Do not assume PENDING arrives before COMPLETE for a transaction. Each event carries enough state to be processed independently — re-query if uncertain.
Log everything
Persist the X-Request-ID, eventId, eventType, and raw body. This is the only audit trail you have during a Buvei-side investigation.
Anti-patterns
- ❌ Doing database writes inline before returning
200. - ❌ Re-parsing JSON for signature verification (use the raw bytes).
- ❌ Treating
409from upstream services as a failure to retry — it usually means "already processed". - ❌ Holding the connection open while you call external services.