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.

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
String

Unique ID for the worker


reason
String

The user failed automated fraud checks
Example

"data": {
    "employee_id": "123",
    "reason": "User failed fraud checks"
}




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