Event types
title: "Event types"
description: "Every webhook event BchainPay emits, with payload shape and when to expect it."
section: "Webhooks"
order: 1
updated: "2026-04-18"
sourcePath: "content/docs/webhooks/events.mdx"
Every webhook is a JSON envelope wrapping a data object that mirrors the API resource at the time of the event.
Envelope
{
"id": "evt_8H2x...91",
"type": "payment_intent.completed",
"created_at": "2026-04-18T12:08:11Z",
"data": { "...": "..." }
}
Use id for idempotent processing — the same event may be delivered more than once.
Payment intents
| Type | When it fires |
|---|
payment_intent.created | Right after POST /v1/payment-intents succeeds. |
payment_intent.processing | First on-chain sighting; not yet at the confirmation threshold. |
payment_intent.completed | Confirmed and credited to the matching pocket. |
payment_intent.expired | expires_at passed without sufficient confirmations. |
payment_intent.canceled | You canceled the intent via the API or dashboard. |
Withdrawals
| Type | When it fires |
|---|
withdrawal.queued | Accepted, waiting for the vault. |
withdrawal.broadcasting | Signed and submitted to the network. tx_hash is now set. |
withdrawal.completed | Confirmed on-chain. |
withdrawal.failed | Broadcast or confirmation failed; pocket balance restored. |
Pockets
| Type | When it fires |
|---|
pocket.credited | Any payment intent completes against this pocket. |
pocket.debited | Any withdrawal completes from this pocket. |
Example payload — payment_intent.completed
{
"id": "evt_8H2x...91",
"type": "payment_intent.completed",
"created_at": "2026-04-18T12:08:11Z",
"data": {
"id": "pi_3L9k...42",
"object": "payment_intent",
"status": "completed",
"pocket_id": "pkt_usdc_polygon",
"amount_cents": 4999,
"settlement_currency": "USDC",
"network": "polygon",
"tx_hash": "0x7d2e...01ab",
"reference": "INV-2026-001"
}
}
