Webhooks

BillerAPI sends webhook events to notify your application when key actions occur. Configure your webhook endpoint in the Client Portal to start receiving events.

Related guide: Webhooks Integration Guide

The Webhook Event object

Attributes

Field	Type	Description
id*	string	Unique event identifier
type*	string	Event type (e.g., request-to-link.created)
created_at*	string	ISO 8601 timestamp when the event occurred
data*	object	Event-specific payload data
client_id*	string	The client this event belongs to

Example Webhook Event object

JSON

{
  "id": "evt_abc123",
  "type": "request-to-link.created",
  "created_at": "2026-04-01T10:00:00Z",
  "client_id": "client_xyz",
  "data": {
    "id": "rtl_abc123",
    "client_user_id": "user_456",
    "biller_id": "test_electric_company",
    "status": "PENDING"
  }
}

Event Types

Event	Description
`request-to-link.created`	A new request-to-link was created
`request-to-link.updated`	A request-to-link status changed
`account-link.created`	A new biller account was successfully linked
`account-link.updated`	An account link status changed (e.g., disconnected)
`link.created`	A link session was created and is ready for the user

EVENTrequest-to-link.created

Sent when a new request-to-link is created. Use this to track when linking flows are initiated for your users.

{
  "id": "evt_001",
  "type": "request-to-link.created",
  "created_at": "2026-04-01T10:00:00Z",
  "client_id": "client_xyz",
  "data": {
    "id": "rtl_abc123",
    "client_user_id": "user_456",
    "biller_id": "test_electric_company",
    "status": "PENDING",
    "metadata": {
      "source": "onboarding"
    },
    "created_at": "2026-04-01T10:00:00Z"
  }
}

EVENTrequest-to-link.updated

Sent when a request-to-link status changes. Includes both the new and previous status for easy state tracking.

{
  "id": "evt_002",
  "type": "request-to-link.updated",
  "created_at": "2026-04-01T10:05:00Z",
  "client_id": "client_xyz",
  "data": {
    "id": "rtl_abc123",
    "client_user_id": "user_456",
    "biller_id": "test_electric_company",
    "status": "COMPLETED",
    "previous_status": "IN_PROGRESS",
    "link_token_id": "lt_token123",
    "updated_at": "2026-04-01T10:05:00Z"
  }
}

EVENTaccount-link.created

Sent when a user successfully links a biller account. This is a good time to trigger an initial bill sync.

{
  "id": "evt_003",
  "type": "account-link.created",
  "created_at": "2026-04-01T10:05:00Z",
  "client_id": "client_xyz",
  "data": {
    "id": "al_xyz789",
    "biller_id": "test_electric_company",
    "biller_name": "Test Electric Company",
    "client_user_id": "user_456",
    "status": "ACTIVE",
    "account_number": "****1234",
    "created_at": "2026-04-01T10:05:00Z"
  }
}

EVENTaccount-link.updated

Sent when an account link status changes. Common transitions include ACTIVE to DISCONNECTED when credentials expire.

{
  "id": "evt_004",
  "type": "account-link.updated",
  "created_at": "2026-04-02T14:30:00Z",
  "client_id": "client_xyz",
  "data": {
    "id": "al_xyz789",
    "biller_id": "test_electric_company",
    "biller_name": "Test Electric Company",
    "client_user_id": "user_456",
    "status": "DISCONNECTED",
    "previous_status": "ACTIVE",
    "error": "credentials_expired",
    "updated_at": "2026-04-02T14:30:00Z"
  }
}

EVENTlink.created

Sent when a link session is created and ready for the user. Contains the session URL and expiration time.

{
  "id": "evt_005",
  "type": "link.created",
  "created_at": "2026-04-01T10:02:00Z",
  "client_id": "client_xyz",
  "data": {
    "link_token_id": "lt_token123",
    "session_url": "https://link.billerapi.com/session/lt_token123",
    "client_user_id": "user_456",
    "biller_id": "test_electric_company",
    "expires_at": "2026-04-01T11:02:00Z"
  }
}

Handling Webhooks

Your webhook endpoint must return a 200 status code within 30 seconds to acknowledge receipt. If BillerAPI does not receive a 200 response, the event will be retried up to 3 times with exponential backoff.

For a complete guide on setting up webhooks, verifying signatures, and handling retries, see the Webhooks Integration Guide.