Webhook Reference Docs

Account Verified as Worker
Account Review
Advance Adjustment
Advance Claimed
Card Activated
Card Deactivated
Invoice Created
Invoice Overdue
Invoice Transfer Initiated
KYC Fallback Failed
KYC Declined
Payment Profile Activated
Payment Profile Deactivated
Wallet Created
Wallet Claimed
Wallet Activated
Wallet Deactivated
Wallet Closed

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.

Example

  {
    "event": "ACCOUNT_VERIFIED_AS_WORKER",
    "event_id": UUID,
    "client_type": "ORGANIZATION",
    "client_id": "100000"
    "data": {
       "first_name": "John",
       "last_name": "Doe",
       "employee_id": "123",
       "account_number": "1234567891234567",
       "routing_number": "084106768",
       "email_address": "[email protected]",
       "phone_number": "5551234567"
     }
   }

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.

event
ACCOUNT_VERIFIED_AS_WORKER

Payload
first_name
String
Worker first name
last_name
String

Worker last name
employee_id
String

Unique ID for the worker
account_number
String

Worker 16-character Branch account number
routing_number
String

Routing number
email_address
String

Worker email address
phone_number
String

Worker phone number
Example

"data": {
    "first_name": "John",
    "last_name": "Doe",
    "employee_id": "123",
    "account_number": "1234567891234567",
    "routing_number": "084106768",
    "email_address": "[email protected]",
    "phone_number": "5551234567",
}

Account Review

Triggered when a worker has been flagged for manual review

event
ACCOUNT_REVIEW

Payload
employee_id
String

Unique ID for the employee
onboarding_link
String

Worker's onboarding link
Example

"data": {
    "employee_id": "123",
    "onboarding_link": "https://branchapp.com/ol1"
}

Advance Adjustment

Triggered when an adjustment is made to an advance

event
ADVANCE_ADJUSTMENT

Payload
adjustment_amount
Long

Amount of the adjustment
advance_id
String

Unique ID of the advance being adjusted
employee_id
String

Unique ID for the employee
original_outstanding_amount
Long

Outstanding amount before adjustment
outstanding_amount
Long

Outstanding amount
timestamp
datetime

Time of adjustment
type
String

Type of adjustment
Example

"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

event
ADVANCE_CLAIMED

Payload
advance_id
String

Unique ID of the advance being adjusted
amount
Long

Amount of the advance
employee_id
String

Unique ID for the employee
timestamp
datetime

Time of adjustment
Example

"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

event
CARD_ACTIVATED

Payload
employee_id
String

Unique ID for the employee
marqeta_card_token
UUID

Unique ID
card_product
String

Name of the card product
card_type
CardType

The type of card, options are:
  • PHYSICAL
  • VIRTUAL
  • UNKNOWN
time_emitted
datetime

Time of activation
Example

"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

event
CARD_DEACTIVATED

Payload
employee_id
String

Unique ID for the worker
marqeta_card_token
UUID

Unique ID
card_product
String

Name of the card product
card_type
CardType

The type of card, options are:
  • PHYSICAL
  • VIRTUAL
  • UNKNOWN
reason_code
CardType

Reason for deactivation, options are:
  • TERMS_OF_SERVICE_VIOLATION
  • CONFIRMED_FRAUD
  • USER_REQUESTED
The card is deactivated due to fraud check failing, fraudulent activity detected, violation of terms of service, or the worker requesting deactivation.
time_emitted
datetime

Time of activation
Example

"data": {
    "employee_id": "123",
    "marqeta_card_token": "Acme_1099_Physical",
    "card_product": "Acme_1099",
    "card_type": "PHYSICAL",
    "reason_code": "USER_REQUESTED",
    "time_emitted": "2023-12-30T15:40:32-08:00"
 }

Invoice Created

Triggered when an invoice is created

event
INVOICE_CREATED

Payload
id
Long

Unique ID for invoice
amount
Long

Amount of the invoice
description
String

Description of the invoice
filename
String

Invoice file name
due_date
date

Date that the invoice is due to be paid
Example

"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

event
INVOICE_OVERDUE

Payload
id
Long

Unique ID
amount
Long

Amount of the invoice
description
String

Description of the invoice
due_date
date

Date that the invoice is due to be paid
Example

"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

event
INVOICE_TRANSFER_INITIATED

Payload
invoice_id
Long

Unique ID for invoice
amount
Long

Amount of the invoice
description
String

Description of the invoice
Example

"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.

event
KYC_FALLBACK_FAILED

Payload
employee_id
String

Unique ID for the worker
Example

"data": {
    "employee_id":"123"
}


KYC Declined

This webhook is triggered when a worker's KYC is declined.

event
KYC_DECLINED

Payload
employee_id
Int

Unique ID for the worker

reason
String

The reason KYC was declined
Example

"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.

event
PAYMENT_PROFILE_ACTIVATED

Payload
employee_id
Int

Unique ID for the worker

active_type
String

The active payment type, options are:
  • WALLET
  • CARD
time_emitted
datetime

Example

"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.

event
PAYMENT_PROFILE_DEACTIVATED

Payload
employee_id
Int

Unique ID for the worker

time_emitted
datetime

Example

"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

event
WALLET_CREATED

Payload
employee_id
String

Unique ID for the worker
account_number
String

Worker 16-character Branch account number
routing_number
String

Routing number for the initialized account
onboarding_link
String

Link sent to employee to start onboarding
Example

"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

event
WALLET_CLAIMED

Payload
employee_id
String

Unique ID for the worker
Example

"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.

event
WALLET_ACTIVATED

Payload
employee_id
String

Unique ID for the worker
account_number
String

Worker 16-character Branch account number
routing_number
String

Routing number for the initialized account
onboarding_link
String

Link sent to employee to start onboarding
is_claimed
Boolean

Indicates if wallet is claimed
Example

"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.

event
WALLET_DEACTIVATED

Payload
employee_id
String

Unique ID for the worker
account_number
String

Worker 16-character Branch account number
routing_number
String

Routing number for the initialized account
reason_code
String

Reason code for deactivation
reason
String

Reason for deactivation
time_emitted
datetime

Time and date of the deactivation
is_claimed
Boolean

Indicates if wallet is claimed
Example

"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.

event
WALLET_CLOSED

Payload
employee_id
String

Unique ID for the worker
account_number
String

Worker 16-character Branch account number
routing_number
String

Routing number for the initialized account
Example

"data": {
    "employee_id": "123",
    "account_number": "1234567891234567",
    "routing_number": "084106768"
}