BVNK Webhooks API
BVNK Webhooks API provides real-time notifications for various events across the BVNK platform. This API specification describes the webhook events that BVNK sends to your configured endpoints.
Webhook Categories
- Status Change Webhooks: Fiat and crypto payment status changes
- Channel Webhooks: Crypto channel transaction events
- Crypto Webhooks: Cryptocurrency transaction lifecycle events
- Customer Webhooks: Customer management and compliance events
- Ledger Webhooks: Wallet creation and reporting events
- Digital Asset Webhooks: Deposit and withdrawal status changes
Authentication
All webhooks include an x-signature header for verification using HMAC-SHA256.
The signature is calculated using your webhook secret key and the raw JSON payload.
Response Requirements
Your webhook endpoint must respond with HTTP 200 status code to acknowledge receipt. The retry policy adds a delay before each retry, starting with a base delay and increasing the time between retries. The delay grows larger after each attempt, but will not exceed 15 minutes. The system will attempt up to 100 times, and after that, no further retries will occur.
Retry policy
If BVNK does not receive a 200 status code, the webhook retry policy will kick in. This includes cases where the endpoint returns a non-2xx status code or fails to respond within the 10-second timeout window. After 10 seconds without a successful response, the delivery attempt is considered failed and will trigger the retry process defined by the webhook policy.
The retry policy adds a delay before each retry, starting with a base delay and increasing it with each retry. The delay grows larger after each attempt, but will not exceed 15 minutes. The system will attempt up to 100 times, and after that, no further retries will occur.
To ensure safe and consistent processing, all webhook events include a unique identifier that receivers should use to implement idempotency. This prevents duplicate event handling if the same webhook is retried multiple times due to timeouts or failed responses. The receiving system should detect repeated event IDs and avoid performing the same business action more than once.
Authentication
- API Key: WebhookSignature
HMAC-SHA256 signature for webhook verification. The signature is calculated using your webhook secret key and the raw JSON payload.
Example verification in different languages:
JavaScript:
const crypto = require('crypto');
const signature = crypto
.createHmac('sha256', secretKey)
.update(payload, 'utf8')
.digest('base64');
Python:
import hmac
import hashlib
import base64
signature = base64.b64encode(
hmac.new(secretKey.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).digest()
).decode('ascii')
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | x-signature |