Webhook Reference Docs
Introduction
This section provides details about the notifications you receive when any of the Branch webhooks that you have registered for is triggered. There are common fields sent for all webhooks, and a payload that differs according to the webhook.
The example at the right shows the common fields at the top, then the payload specific to the webhook contained in the data block, which is sent to you encrypted. Each webhook example below includes only the data block.
{
"event": "WALLET_CREATED",
"event_id": UUID,
"client_type": "ORGANIZATION",
"client_id": "100000"
"data": {
"employee_id": "123",
"account_number": "1234567891234567",
"routing_number": "084106768",
"onboarding_link": "https://branchapp.com/ol1"
}
}
Test with Postman
Easily test Webhook integrations by downloading the pre-configured Webhook Events Postman collection. Just set your organizationID
and apiKey
in the collection variables.
Account Verified as Worker
This webhook is triggered when a worker is verified on an organization's roster. Routing and account number will return null if the worker's wallet has not yet been created.
"data": {
"employee_id": "123",
"account_number": "1234567891234567",
"routing_number": "084106768",
}
Account Review
Triggered when a worker has been flagged for manual review
"data": {
"employee_id": "123",
"onboarding_link": "https://branchapp.com/ol1"
}
Advance Adjustment
Triggered when an adjustment is made to an advance
"data": {
"adjustment_amount": 641,
"advance_id": "18d99mn3bvf78094",
"employee_id": "123",
"original_outstanding_amount": 99,
"outstanding_amount": 444,
"timestamp": "2023-12-30T15:40:32-08:00",
"type": "tp_pull"
}
Advance Claimed
Triggered when a worker claims an advance
"data": {
"advance_id": "18d99mn3bvf78094",
"amount": 444,
"employee_id": "123",
"timestamp": "2023-12-30T15:40:32-08:00"
}
Card Activated
Triggered when a worker activates their card
- PHYSICAL
- VIRTUAL
- UNKNOWN
"data": {
"employee_id": "123",
"marqeta_card_token": "Acme_1099_Physical",
"card_product": "Acme_1099",
"card_type": "PHYSICAL",
"time_emitted": "2023-12-30T15:40:32-08:00"
}
Card Deactivated
Triggered when a worker deactivates their card
- PHYSICAL
- VIRTUAL
- UNKNOWN
- DISABLED_AUTO_DISBURSEMENT
- LOST_OR_STOLEN
- OTHER
"data": {
"employee_id": "123",
"marqeta_card_token": "Acme_1099_Physical",
"card_product": "Acme_1099",
"card_type": "PHYSICAL",
"reason_code": "LOST_OR_STOLEN",
"time_emitted": "2023-12-30T15:40:32-08:00"
}
Invoice Created
Triggered when an invoice is created
"data": {
"id": 399742129664,
"amount": 12456,
"description": "Invoice created for John Doe",
"filename": "j_doe_invoice_11",
"due_date": "2023-12-30"
}
Invoice Overdue
Triggered when an invoice is overdue
"data": {
"id": 399742129664,
"amount": 12456,
"description": "Invoice not paid by due dates",
"due_date": "2023-12-30"
}
Invoice Transfer Initiated
Triggered when an invoice transfer is initiated
"data": {
"invoice_id": 399742129664,
"amount": 12456,
"description": "Transferring invoice to XYZ"
}
KYC Fallback Failed
This webhook is triggered when KYC fallback ID upload verification has failed. This means that the worker is not payable through Branch.
"data": {
"employee_id":"123"
}
KYC Declined
This webhook is triggered when a worker's KYC is declined.
"data": {
"employee_id": "123",
"reason": "Document invalid"
}
Payment Profile Activated
This webhook is triggered when a payment method is added to a worker's account.
- WALLET
- CARD
"data": {
"employee_id": "123",
"active_type": "WALLET",
"time_emitted": "2023-12-30T15:40:32-08:00"
}
Payment Profile Deactivated
This webhook is triggered when a payment method has been removed from a worker’s account, and the worker is no longer able to receive a disbursement.
"data": {
"employee_id": "123",
"time_emitted": "2023-12-30T15:40:32-08:00"
}
Wallet Created
Triggered when the worker passes KYC and a wallet is created
"data": {
"employee_id": "123",
"account_number": "123456789",
"routing_number": "084106768",
"onboarding_link": "https://branchapp.com/ol1"
}
Wallet Claimed
Triggered when a worker downloads the application and claims a pre-initialized account
"data": {
"employee_id":"123"
}
Wallet Activated
When a worker's identity is verified a wallet is created. It is not usable however until the worker passes additional KYC checks. When the KYC checks pass, this webhook is triggered.
"data": {
"employee_id": "123",
"account_number": "1234567891234567",
"routing_number": "084106768",
"onboarding_link": "https://branchapp.com/ol1",
"is_claimed": false
}
Wallet Deactivated
This webhook is triggered when a worker's wallet is deactivated. This could be due to Branch confirming fraud, or the worker requesting that their account be closed.
- TERMS_OF_SERVICE_VIOLATION
- CONFIRMED_FRAUD
- USER_REQUESTED
"data": {
"employee_id": "123",
"account_number": "1234567891234567",
"routing_number": "084106768",
"reason_code": "USER_REQUESTED",
"reason": "Worker Resigned",
"time_emitted": "2023-12-30T15:40:32-08:00",
"is_claimed": true
}
Wallet Closed
This webhook is triggered when a wallet is closed. The worker is reset and can onboard again.
"data": {
"employee_id": "123",
"account_number": "1234567891234567",
"routing_number": "084106768"
}