BVNK Payments Webhooks API (v.3 draft)
Draft spec, staged separately from bvnk-webhooks-api-3.0.yaml for review. It is expected to be merged into that file once the Payments v.3 payouts, payins, and channels endpoints ship; do not treat it as a permanent standalone spec.
Covers the four new v.3 payment webhooks from the API Unification project: one consolidated status-change event each for payouts and payins (replacing more than half a dozen v1 event names), plus channel:created and channel-payin:status-change for the crypto channels migration from v2.
Payment exceptions (over-payment, under-payment, late arrival, and refunds) are no longer distinct event names. They are the same status-change event, distinguished by the labels[] array and relatedPayments[] on the payload. See the companion migration guide for the full v1-to-v3 event name mapping table.
Do not strictly serialise webhook fields you do not need. Only read the fields your platform uses.
Authentication
All webhooks include an x-signature header for verification using HMAC-SHA256, unchanged from existing BVNK webhooks.
Response requirements
Your webhook endpoint must respond with HTTP 200 to acknowledge receipt, within the standard 10-second timeout, or BVNK's retry policy takes over.