Bill Navigator Webhook Events

Bill switch webhook events will notify you when a user has successfully added a card or bank account from Link token creation to a merchant platform.

bill_switch.added

A bill_switch job to add a new card or account to a merchant was completed.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`params` (optional)	object	Parameters of the job, if applicable.
`params.card_name` (optional)	string	The card name as provided in Link token creation used for bill switch. This field will be present if the switch occurred using a card and not an account.
`params.action`(optional)	string	Indicates whether the `direct_deposit_switch` was a `full_switch` or a `partial_switch`. Will not be set for select partner-based switches where we do not receive this information from our partner.
`params.allocation` (optional)	object	The allocation that was created/updated during a `direct_deposit_switch`. Only present when `params.action` is `partial_switch` or the switch was performed with a card.
`params.allocation.type` (optional)	string	Indicates whether this is a `remainder`, `amount` or `percentage` allocation. Will be set if `params.action` is `partial_switch`.
`params.allocation.value` (optional)	integer	The value (if any) for this allocation. Will be set if the `type` is `percentage` or `amount`.
`params.allocation.target.account_name` (optional)	string	The account name (if any) for this allocation. We recommending including `name` during Link token creation if you send multiple accounts. This field will be present if the switch occurred using an account and not a card.
`params.allocation.target.account_type`(optional)	string	The account type for this allocation. Will be either `checking` or `savings`. This field will be present if the switch occurred using an account and not a card.
`outcome`	string	The outcome of the job, either `success`, `error`, or `pending`. If `pending`, you will receive another webhook event with `outcome` as `success` or `error` within 24 hours.

Sample Webhook Event

{
  "event": "bill_switch.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "card_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "card_name": "My Debit Card",
      "action": "full_switch"
    }
  }
}