Webhook events for internal transfers between customers, including transfers across organizations.
The receiving account gets an internal.completed webhook when an internal transfer credits its balance. The sending account receives payouts.* webhooks to track its outgoing payment.
When internal.completed fires
internal.completed fires- Customer-to-customer transfer. When a transfer initiated through the Payout API or the admin console completes, the destination account receives the event.
- Auto-sweep. When funds from a sub-account deposit sweep to the main account, the main account receives the event.
- Payout funding. When the main account funds a sub-account for a payout on behalf of a sub-account, the sub-account receives the event. It confirms receipt of the internal funding transfer.
Example payload
In this example, BZ-RECV-1234 receives 1,000 USDC from BZ-SEND-1234.
{
"event_name": "internal.completed",
"resource": {
"type": "transfers",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
},
"data": {
"status": "COMPLETED",
"account_id": "BZ-RECV-1234",
"transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"direction": "IN",
"from_account_id": "BZ-SEND-1234",
"asset": "USDC",
"amount": "1000.00",
"memorandum": "Payment for invoice #12345",
"created_at": "2024-01-22T12:00:00.000Z",
"modified_at": "2024-01-22T12:00:00.000Z"
}
}Handling the credit
Use data.account_id to identify who received the funds. The from_account_id field identifies who sent them.
Deduplicate deliveries using the X-Webhook-Event-Id header so a retry or replay records the credit only once.
