Webhooks

bill.created

A new bill was extracted for a linked account. Subscribers typically refetch the full resource via GET /v1/bills/:id to get the amount, due date, and statement.

Follow-up to fetch the full resource: GET /v1/bills/:id — authenticate with link-scoped Bearer.

bill.updated

A bill's status changed. The `change` field on `data.object` discriminates the sub-type so subscribers can branch without a round-trip GET for every update.

Follow-up to fetch the full resource: GET /v1/bills/:id — authenticate with link-scoped Bearer.

change values at a glance: paid — bill flipped to PAID (+paid_reason, paid_at); partially_paid — partial payment received (+paid_reason, paid_at); status_reverted — bill reverted from PAID/PARTIALLY_PAID to PENDING (+previous_status, revert_reason, reverted_at); statement_refreshed — statement re-extracted, refetch for new balance/due date; match_status — payment-matching result changed (+match_status, matched_payment_ref).

PAID is not terminal. A bill.updated with change='status_reverted' may follow within 24 h if the nightly reconciliation job finds the prior bill still in previous_balance on the next statement. Surface this prominently to end users.

bill.deleted

A bill was deleted. The follow-up GET will return 404; record the deletion and acknowledge with 200.

link.completed

A link is fully established and ready to retrieve bills. Fires once per link, after the user finishes the Connect flow.

Follow-up to fetch the full resource: GET /v1/link/:id — authenticate with IAM (API key).

connection.ready

The first successful bill retrieval for a link completed — the connection is fully warmed up and bills are available. Fires exactly once per link, after `link.completed` and alongside the first `bill.created` events. Use it to flip "Syncing your bills…" UX to a ready state.

Follow-up to fetch the full resource: GET /v1/link/:id — authenticate with IAM.

link_token.completed

A BACKGROUNDED connect flow completed server-side: the user chose "continue in background" on the hosted connect page, account discovery finished, all discovered accounts were auto-selected, and BillerAPI exchanged the public token internally. The resulting link already exists and bill retrieval is starting — no client-side exchange is needed (the public token is never exposed on this path). Interactive flows do NOT fire this event; they keep the `link.completed` surface driven by your own `POST /v1/link-tokens/exchange` call.

Follow-up to fetch the full resource: GET /v1/link/:id — authenticate with IAM.

link.session_finished

A HOSTED connect session finished. Fires when you mint a link token with `hosted: {}` and redirect the user to the returned `hosted_url` (BillerAPI's standalone hosted connect page). `status` is `completed` — the user finished and BillerAPI already exchanged the public token SERVER-SIDE, so `link_id` is populated and no client-side exchange is needed (the public token is never exposed) — or `exited` — the user closed/abandoned the page (`exit_reason` = `user_closed` | `error`). It does NOT fire on token expiry (that is a `link.disconnected`). Pair it with `connection.ready` / `bill.created` to know when bills are available.

Follow-up to fetch the full resource: GET /v1/link/:id — authenticate with IAM.

link.disconnected

A link became unusable. The `reason` field on `data.object` discriminates the cause. All three reasons may require a user-facing action to recover access.

Follow-up to fetch the full resource: GET /v1/link/:id — authenticate with IAM.

reason values at a glance: expired — access token lifetime ended; user can reconnect; credentials_rejected — stored credentials rejected; user must re-enter credentials (recoverable without a full re-link); check credential_rejection_reason for sub-reason (INVALID_CREDENTIALS vs CONNECTION_DEGRADED); revoked — user unlinked or biller revoked consent; terminal — prompt user to start a new link if they want to reconnect.

link_request.created

A link request was created and has a known biller. Use this to track when a server-initiated linking flow begins (e.g. before the user has been sent the Connect URL). Invariant: the payload always carries a non-null `biller_id`.

Follow-up to fetch the full resource: GET /v1/link/request-to-link/:id — authenticate with IAM.

link_request.cancelled

A link request was cancelled before linking completed. A `reason` field distinguishes the cancellation type.

Follow-up to fetch the full resource: GET /v1/link/request-to-link/:id — authenticate with IAM.

onboarding.submitted

A request to onboard a new biller was accepted. Watch for the matching `onboarding.failed` if the biller integration cannot be built.

Follow-up to fetch the full resource: GET /v1/biller/onboarding/:id — authenticate with IAM.

This event is biller-scoped — it carries no user_id. A single biller onboarding can serve any number of users that subsequently link to it.

onboarding.completed

A biller onboarding request finished successfully — the biller integration is now available and links can be created against it.

Follow-up to fetch the full resource: GET /v1/biller/onboarding/:id — authenticate with IAM.

onboarding.failed

A biller onboarding request could not be completed. The follow-up GET returns the failure reason in the resource body.

Follow-up to fetch the full resource: GET /v1/biller/onboarding/:id — authenticate with IAM.

customer.message.created

Your service sent a message to a customer via POST /customers/{user_aid}/messages and it was accepted. The push notification + in-app inbox row land in BillEBox for the customer. v1 in-app channel only; email/SMS deferred. Two categories: marketing (opt-in required) and account_update (default opt-in; opt-out only).

customer.message.complaint

A customer tapped Report on a `customer.message.created` you previously sent. BillerAPI has (a) added the (clientId, customer_user_aid) pair to your suppression list — future sends to this customer return HTTP 200 with `delivery_status: "suppressed"` — and (b) revoked the customer's marketing consent. You should mirror the suppression in your own CRM and respect it across all your channels (email, SMS, mail) to stay on the right side of CAN-SPAM / TCPA / state UDAP rules.

payment.observed

A historical payment was observed on the biller's portal (Payment History tab). Distinct from a payment your service initiated — this is what the biller already recorded. The `id` is stable across webhook retries and re-scrapes (server-side deterministic SHA-256). No ordering guarantee with `bill.created`; consumers must tolerate either order. Field policy is additive-only; ignore unknown fields.

pay.scheduled

A payment attempt was scheduled and is being processed (covers both the initial schedule and the submitted-awaiting-confirmation transition — both deliver as `pay.scheduled`). Fetch GET /api/pay/v1/payments/:attemptId for the full record. Note: payment execution is currently gated off — that endpoint returns 501 (PAYMENT_EXECUTION_NOT_AVAILABLE) until the pay pillar is enabled.

Follow-up to fetch the full resource: GET /api/pay/v1/payments/:attemptId — authenticate with IAM (gated — returns 501 until pay is enabled).

pay.succeeded

A payment attempt succeeded. Carries the confirmation number and amount when available so you can reconcile without a round-trip.

Follow-up to fetch the full resource: GET /v1/payment-attempts/:id — authenticate with IAM.

pay.failed

A payment attempt failed. The `code` field carries a machine-readable failure reason when available.

Follow-up to fetch the full resource: GET /v1/payment-attempts/:id — authenticate with IAM.

pay.escalated

A payment attempt was escalated for manual review (e.g. an unexpected biller-portal state). The `reason` field describes why.

Follow-up to fetch the full resource: GET /v1/payment-attempts/:id — authenticate with IAM.

insight.created

A new insight was generated for one of your users — a bill/biller-level observation such as an anomaly, duplicate charge, new biller, overdue risk, savings opportunity, or a line-item-level finding (new fee, line-item spike, usage anomaly). Minimal-with-refetch: fetch GET /v1/insights/:id for the full evidence, reasoning, and proposed actions. The `proposed_actions` array is client-agnostic (`action_type` + `label` + `params`) — never an executable command. New insight `type` values may be added over time; treat an unrecognized `type` as a generic insight rather than rejecting the event. The `evidence_json` on the fetched record carries type-specific keys: `bill_anomaly` → `new_total`, `median_total`, `ratio`, `threshold_ratio`, `sample_size`, `currency`; `duplicate_charge` → `amount`, `currency`, `matched_bill_id`, `days_apart`, `window_days`; `new_biller` → `biller_id`, `merchant_name`, `amount`, `currency`; `overdue_risk` → `due_date`, `days_until_due`, `window_days`, `status`, `amount`, `currency`; `new_fee` → `description`, `kind`, `signed_amount`, `currency`; `line_item_spike` → `description`, `signed_amount`, `median_amount`, `ratio`, `threshold_ratio`, `currency`; `usage_anomaly` → `description`, `usage_quantity`, `usage_unit`, `median_quantity`, `ratio`, `threshold_ratio`. Amounts are signed magnitudes (a credit/payment/adjustment reads negative); `ratio` is `current / median`.

Follow-up to fetch the full resource: GET /v1/insights/:id — authenticate with IAM.

insight.updated

An insight's lifecycle status changed (snoozed, dismissed, or resolved). The `status` field on `data.object` carries the new state so you can reconcile your projection without a round-trip GET. Fetch GET /v1/insights/:id for the full record.

Follow-up to fetch the full resource: GET /v1/insights/:id — authenticate with IAM.

biller.unsupported

The platform marked a biller as unsupported (e.g. the biller's website changed in a way that makes automation impossible). Prompt the affected user to manage this biller manually until the integration is restored.

Follow-up to fetch the full resource: GET /v1/billers/:id — authenticate with IAM.

webhook.replay-requested

An operator triggered a manual replay of a dead-lettered webhook. Useful as an audit signal; clients usually do not need to handle this.