Notification settings

This is not the result webhook. Matched, ambiguous, expired, and bank-movement payloads are the result webhook, configured under Webhook settings. This page is a separate channel for operational alerts — when a login needs a one-time code, when a login fails, when a scrape fails.

The notification webhook lets an external service react to what is happening to an account, without polling. Its most common use is assisted login: your service is told the moment a code is needed and submits it through the External API.

What it notifies

You subscribe to any of three events:

The payload carries both names: type is the subscribable name above, and status is Reconbanker's internal event name (the same value you would see on the realtime stream).

The fields

The notification webhook is configured with four account settings, saved through PUT /accounts/:accountId/config (see Accounts):

• notification_endpoint_url - where Reconbanker POSTs the events. Leave empty to disable.
• notification_auth_type - bearer or api_key (or empty for no auth header).
• notification_auth_token - the token to send. Masked in the config response.
• notification_events - the list of events you want, any of assistance_required, login_failed, scrape_failed. An event not in this list is never delivered.

These are entirely separate from the webhook_* fields that drive the result webhook.

Auth headers

Reconbanker authenticates to your endpoint the same way it does for the result webhook:

• bearer - sends Authorization: Bearer <token>.
• api_key - sends Authorization: Api-Key <token>.

If notification_auth_token is empty, no Authorization header is sent.

The payload

Every notification is an HTTP POST with this body:

{
  "account_id": "b9c224b3-3c2b-42bd-b23e-337ae0185690",
  "type": "assistance_required",
  "status": "assistance.requested",
  "data": { "descriptor": { "length": 6, "type": "numeric" } },
  "occurred_at": "2026-06-13T03:00:00.000Z"
}

• account_id - the account the event is about.
• type - the subscribable event name.
• status - the internal event name.
• data - event-specific detail. For assistance_required it is the OTP descriptor; it may be null for events that carry no payload.
• occurred_at - ISO 8601 timestamp.

Delivery and retries

Notification delivery is backed by a Redis stream. If your endpoint does not accept a delivery, the entry stays un-acknowledged and is redelivered after an idle window rather than on a fixed schedule. There is no built-in cap of three attempts — a failing endpoint keeps being retried until it succeeds or the stream entry ages out. Make your handler idempotent, since a delivery may arrive more than once.

This differs from the result webhook's fixed backoff (see Webhook settings → Retry behavior). Crucially, the OTP login path never waits on this webhook: a down endpoint slows your notifications but never blocks a scrape.

How this differs from the result webhook

See also

• Account settings - where these fields live among all account toggles.
• Webhook settings - the separate result webhook.
• Automate OTP submission - the integration that consumes assistance_required.
• Accounts - the config endpoint that saves these fields.