API ReferenceWebhooks
Overview
How Buvei delivers real-time events to your endpoint.
Buvei sends webhooks for card lifecycle events, transactions, and KYC outcomes. Webhooks are HTTP POST requests with a JSON body, signed with the same HMAC-SHA256 algorithm as outbound API calls.
Anatomy
Every webhook carries the four security headers and a JSON envelope:
{
"eventId": "e_abc123def456",
"eventType": "TRANSACTION",
"timestamp": 1640995700000,
"data": {
// event-specific payload
}
}| Field | Type | Description |
|---|---|---|
eventId | string | Globally unique event id. Use this to de-duplicate retries. |
eventType | string | Event discriminator — see the event reference. |
timestamp | integer | Milliseconds since epoch when the event was emitted. |
data | object | Event-specific payload. See the per-event pages. |
Event types
TRANSACTION
Card authorisations, captures, declines, refunds, reversals.
CARD_CREATED
A new virtual card is provisioned and ready for use.
CARD_DELETED
A card has been permanently deleted; remaining balance is refunded.
CARD_ENABLED
A frozen card was unfrozen by user or admin.
CARD_DISABLED
A card was frozen by user or admin.
CARDHOLDER_KYC_STATUS
A KYC cardholder transitioned out of PENDING.
Next
- Security — verify inbound signatures.
- Retry policy — what happens when your endpoint is unhealthy.
- Best practices — idempotency, ordering, timeouts.