API ReferenceWebhooks
Webhook Security
Verifying inbound webhook signatures.
Webhooks carry the same four headers as outbound API calls:
| Header | Description |
|---|---|
X-API-Key | Your API key (helps you route between projects). |
X-Timestamp | Event emission time in milliseconds. |
X-Nonce | Unique event nonce. |
X-Signature | HMAC-SHA256 of the payload string, base64-encoded. |
Verification
Reconstruct the signing payload from the request you just received and compare:
payload = timestamp + "." + method + "." + path + "." + nonce + "." + rawBody
expected = base64(hmac_sha256(payload, api_secret))rawBody is the request body bytes as received — do not parse and re-serialise.
Always use a constant-time comparison (e.g. crypto.timingSafeEqual in Node, hmac.compare_digest in Python) when comparing signatures. String equality is vulnerable to timing attacks.
Minimum guarantees
- Authenticity — only Buvei could have produced the signature.
- Integrity — the body was not modified in transit.
- Replay protection — combine with
eventIdde-duplication for at-most-once processing.