Webhooks

Bank linking is asynchronous. After you hand a user off to the widget, they might sign in and pick accounts in ten seconds — or wander off and finish twenty minutes later on their phone. Webhooks let LedgerSync tell you the instant something happens, so you never have to sit in a polling loop. The single most important event is connection.active: it fires when a user finishes linking and data starts flowing. That payload carries the canonical connection id (like con_FINICITY_41294) — the only id that works on /accounts, /transactions, and /statements. Subscribe to webhooks and you get it delivered for free.

Webhooks are the recommended way to learn about connection state. You can poll GET /v3/operations/{id} during the initial link (see Connect a bank), but for everything after — refreshes, disconnects, capability changes — webhooks are the only push channel.

The easiest path is the Webhooks page in the portal: paste your endpoint URL, tick the events you want, and copy the signing secret. It’s the recommended day-to-day way to manage subscriptions, rotate secrets, and inspect recent deliveries. To do it programmatically, POST /v3/webhooks/subscriptions:

curl -X POST https://api-sandbox.ledgersyncappv2.com/v3/webhooks/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/ledgersync",
    "event_types": [
      "connection.active",
      "connection.failed",
      "connection.disconnected",
      "account.refresh.completed"
    ]
  }'

{
  "id": "whsub_01HXYZ...",
  "url": "https://yourapp.com/webhooks/ledgersync",
  "event_types": [
    "connection.active",
    "connection.failed",
    "connection.disconnected",
    "account.refresh.completed"
  ],
  "signing_secret": "whsec_9f2c...shown-once"
}

The signing_secret is shown once, at creation. Store it somewhere safe immediately — you’ll need it to verify every delivery. If you lose it, rotate the secret from the portal Webhooks page.

Event catalog

There are exactly eight real events, plus a webhook.test event you can fire on demand. Subscribe only to the ones you handle.

Event	Fires when
`connection.requires_action`	The connection is waiting on the user in the widget (sign-in, MFA, account pick).
`connection.active`	The user finished linking. Data is flowing. Carries the canonical connection id.
`connection.failed`	Bad credentials or an aggregator-reported failure. The link did not complete.
`connection.disconnected`	The user revoked access, or the connection needs a re-link.
`connection.capability_changed`	A single capability on an active connection flipped working ↔ not-working.
`account.refresh.completed`	A background data refresh for an account finished successfully.
`account.refresh.failed`	A background data refresh for an account failed.
`statement.available`	A bank statement PDF was stored for an account for the first time and is ready to download.
`webhook.test`	A manual test delivery you triggered. Safe to ignore in business logic.

See Connection lifecycle for how initiated → requires_action → active (and the failure paths) fit together as a state machine.

There is no connection.initiated event. The initiated connection status exists in the state machine, but the first webhook every new link produces is connection.requires_action. Subscriptions listing an unknown event type are rejected with validation_failed.

There is also no account-added event. When a client opens a new account at a bank they already linked, nothing is pushed to you. connection.active fires on the transition into active, so an already-active connection that stays active produces no event, and account.refresh.completed tells you a refresh finished, not that the account set changed.To find the new account, re-list GET /v3/accounts?client_id=...&connection_id=... and diff on account id. See Adding a new account.

Delivery shape

Every delivery is an HTTP POST to your URL with a JSON body and these X-LS-Webhook-* headers:

Header	Meaning
`X-LS-Webhook-Event-Id`	Stable unique id for this event. Dedupe on it (same value as `event_id` in the body).
`X-LS-Webhook-Event-Type`	The event type, e.g. `connection.active`. Lets you route before parsing.
`X-LS-Webhook-Timestamp`	Unix seconds when we produced the event. Part of the signed payload and used for replay protection.
`X-LS-Webhook-Signature`	`hex(HMAC-SHA256(signing_secret, timestamp + "." + raw_body))`. Verify before trusting anything.
`X-LS-Webhook-Signature-Prev`	Present only for 24h after you rotate the signing secret — the same signature under your previous secret. Accept either while you roll your verifier so a rotation never drops a delivery.

Every body shares the same base fields — event_id, type, created_at, api_version, livemode — plus a data object whose shape depends on the event:

Example delivery body

{
  "event_id": "evt_01HXYZ...",
  "type": "connection.active",
  "created_at": "2026-07-07T14:22:05Z",
  "api_version": "2026-05-22",
  "livemode": false,
  "data": {
    "connection": {
      "id": "con_FINICITY_41294",
      "client_id": "cli_01HXYZ...",
      "source": "FINICITY",
      "status": "active"
    }
  }
}

Verify the signature

Never trust a delivery you haven’t verified. The signed payload is the timestamp header, a literal ., then the raw body:

signed_payload = X-LS-Webhook-Timestamp + "." + raw_body
expected       = hex( HMAC-SHA256( signing_secret, signed_payload ) )

Compare expected to X-LS-Webhook-Signature in constant time. Also reject anything whose X-LS-Webhook-Timestamp is more than five minutes old — that stops replay attacks.

Sign the raw bytes of the body, exactly as received, prefixed with timestamp + ".". If your framework parses JSON and re-serializes it, the bytes change and the signature won’t match. Capture the raw body before any JSON middleware touches it.

import hmac, hashlib, time
from flask import Flask, request, abort

SIGNING_SECRET = b"whsec_9f2c..."
MAX_AGE_SECONDS = 5 * 60

app = Flask(__name__)

@app.post("/webhooks/ledgersync")
def handle():
    raw = request.get_data()  # raw bytes, before JSON parsing
    timestamp = request.headers.get("X-LS-Webhook-Timestamp", "")
    signature = request.headers.get("X-LS-Webhook-Signature", "")

    # Reject stale deliveries (replay protection)
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > MAX_AGE_SECONDS:
        abort(400)

    # Signed payload = timestamp + "." + raw body
    signed = (timestamp + ".").encode("utf-8") + raw
    expected = hmac.new(SIGNING_SECRET, signed, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature):
        abort(401)

    event = request.get_json()
    # ... dedupe on event["event_id"], enqueue, return fast ...
    return "", 200

const crypto = require("crypto");
const express = require("express");

const SIGNING_SECRET = "whsec_9f2c...";
const MAX_AGE_SECONDS = 5 * 60;

const app = express();

// Capture the RAW body — do not let express.json() reserialize it.
app.post(
  "/webhooks/ledgersync",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body; // Buffer of raw bytes
    const timestamp = req.get("X-LS-Webhook-Timestamp") || "";
    const signature = req.get("X-LS-Webhook-Signature") || "";

    // Reject stale deliveries (replay protection)
    const age = Math.abs(Date.now() / 1000 - Number(timestamp));
    if (!/^\d+$/.test(timestamp) || age > MAX_AGE_SECONDS) {
      return res.sendStatus(400);
    }

    // Signed payload = timestamp + "." + raw body
    const signed = Buffer.concat([Buffer.from(timestamp + "."), raw]);
    const expected = crypto
      .createHmac("sha256", SIGNING_SECRET)
      .update(signed)
      .digest("hex");

    const a = Buffer.from(expected);
    const b = Buffer.from(signature);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(401);
    }

    const event = JSON.parse(raw.toString("utf8"));
    // ... dedupe on event.event_id, enqueue, return fast ...
    res.sendStatus(200);
  }
);

During a secret rotation, deliveries also carry X-LS-Webhook-Signature-Prev for 24h — the same payload signed with your previous secret. Accept a match on either header while you roll the new secret across your instances, and a rotation never drops an event.

Use a constant-time comparison — hmac.compare_digest in Python, crypto.timingSafeEqual in Node. A plain == leaks timing information an attacker can use to forge signatures.

Retries and idempotency

If your endpoint doesn’t return a 2xx quickly, we retry with exponential backoff for up to 24 hours. That means:

Return 2xx within 30 seconds. Do the minimum — verify, enqueue, respond. Push slow work (DB writes, downstream calls) onto a background queue. A slow handler looks like a failure and gets retried.
Deliveries can repeat. A retry after a network blip — or a delivery you already processed but responded to slowly — means the same event can arrive more than once. Dedupe on event_id. Treat it as an idempotency key: if you’ve seen it, ack and move on.

Idempotent handling

if seen_before(event["event_id"]):
    return "", 200          # already processed — ack and skip
mark_seen(event["event_id"])
enqueue(event)              # do the real work off the request path
return "", 200

Order is not guaranteed under retries. Design handlers to be self-contained: react to the state in data, don’t assume the previous event already landed.

Ordering

Webhooks are not delivered in order. There is no sequence counter on the envelope, and retries run on their own schedule — a delivery that failed and is being retried can arrive after an event that was produced later. Concretely:

A connection.failed can land before the connection.requires_action that preceded it.
A slow-retried account.refresh.completed can arrive after a newer refresh for the same account.
A back-pull of older statements means statement.available can deliver an earlier statement_date after a later one. Order statements by statement_date, not by arrival.
Two events produced milliseconds apart can arrive in either order.

So don’t build a state machine that assumes the previous event already landed. Treat every webhook as a signal, not a source of truth: it tells you something changed on this connection — then you re-fetch the current state to act on it.

The pattern

Verify the signature.
Dedupe on event_id (X-LS-Webhook-Event-Id) — skip if seen.
GET /v3/connections/{id} to read the CURRENT status.
Reconcile your local state to what the API returns.

Because step 3 always reads current truth, out-of-order arrival is harmless: even if connection.failed shows up before connection.requires_action, the GET /v3/connections/{id} you run for each one returns the connection’s real, latest status — so you converge on the right state regardless of arrival order.

Every envelope carries created_at — the time the event was produced. If you need a tiebreaker (e.g. to ignore a stale event you’ve already superseded), compare created_at, not the X-LS-Webhook-Timestamp header. The header is regenerated on each delivery attempt (it’s the send time, used for replay protection), so a retried event’s header timestamp reflects when it was re-sent, not when it happened. created_at is stable across retries.

Never treat a webhook payload’s status as authoritative when order matters. The data in a late-arriving retry reflects the state at the time that event was produced, which may already be stale. When you need to act, re-fetch with GET /v3/connections/{id}.

Test-fire a delivery

Once a subscription exists, send yourself a real signed delivery:

Fire a test event

curl -X POST \
  https://api-sandbox.ledgersyncappv2.com/v3/webhooks/subscriptions/whsub_01HXYZ.../test \
  -H "Authorization: Bearer sk_test_..."

The test delivery is signed with your real signing secret, so it exercises your verification code end-to-end. It also bypasses the event_types filter, so you can trigger it regardless of what you subscribed to. Use it to confirm your endpoint is reachable, your signature check passes, and your dedupe logic works before you rely on live events.

`connection.capability_changed` in depth

An active connection isn’t all-or-nothing. A bank might keep serving transactions while its statements feed breaks for a week. connection.capability_changed tells you when one individual capability flips between working and not-working — so you can, say, warn a user that statements are temporarily unavailable without tearing down the whole connection. Capabilities that can change:

Capability	Covers
`transactions`	Transaction data feed.
`balance`	Current balance.
`available_balance`	Available (spendable) balance.
`statements`	Statement documents.
`check_images`	Check image retrieval. FDE-only — read them with the check routes.

Capability statuses: succeeded, failed, skipped, unsupported, pending.

Hysteresis: no flapping

We don’t fire on every hiccup. A capability only transitions after a run of consistent observations:

failed after 3 consecutive failed observations.
succeeded after 2 consecutive succeeded observations.
Sentinel statuses (unsupported, skipped, pending) are not debounced — they flip immediately and arrive with consecutive_observations: 1.

This debounce keeps a single transient error from spamming you. The event fires only on a real transition — not on every refresh that happens to agree with the current state.

Payload

connection.capability_changed

{
  "event_id": "evt_01HXYZ...",
  "type": "connection.capability_changed",
  "created_at": "2026-07-07T14:22:05Z",
  "api_version": "2026-05-22",
  "livemode": false,
  "data": {
    "connection": {
      "id": "con_FINICITY_41294",
      "client_id": "cli_01HXYZ...",
      "source": "FINICITY"
    },
    "change": {
      "capability": "statements",
      "previous_status": "succeeded",
      "current_status": "failed",
      "consecutive_observations": 3,
      "last_error": {
        "code": "statements_not_supported",
        "message": "This institution doesn't expose statements.",
        "type": "api_error",
        "category": "CAPABILITY_UNAVAILABLE"
      }
    }
  }
}

The per-capability detail lives under data.change. previous_status and current_status tell you the direction of the flip; consecutive_observations is how many in a row triggered it (3 for a fail, 2 for a recovery); last_error is populated only when current_status is failed.

Other payload shapes

Most events carry data.connection (shown above). Three carry a different data. connection.requires_action adds an action object telling you what the user must do. The common one is widget_url:

connection.requires_action

{
  "event_id": "evt_...",
  "type": "connection.requires_action",
  "created_at": "2026-07-07T14:22:05Z",
  "api_version": "2026-05-22",
  "livemode": false,
  "data": {
    "connection": {
      "id": "con_...",
      "client_id": "cli_...",
      "source": "FINICITY",
      "status": "requires_action"
    },
    "action": {
      "kind": "widget_url",
      "widget_url": "https://connect.ledgersyncappv2.com/w/...",
      "expires_at": "2026-07-07T15:22:05Z"
    }
  }
}

action.kind is a discriminated union — widget_url (open it), mfa_challenge (carries challenge_id + questions), or reauthorize. Branch on kind. account.refresh.completed carries data.account, not data.connection:

account.refresh.completed

{
  "event_id": "evt_...",
  "type": "account.refresh.completed",
  "created_at": "2026-07-07T14:22:05Z",
  "api_version": "2026-05-22",
  "livemode": false,
  "data": {
    "account": {
      "id": "acc_FINICITY_889201",
      "connection_id": "con_FINICITY_41294",
      "source": "FINICITY",
      "refreshed_at": "2026-07-07T14:22:05Z",
      "new_transaction_count": 12,
      "current_balance": { "amount": 4210.55, "iso_currency_code": "USD" },
      "available_balance": { "amount": 3980.10, "iso_currency_code": "USD" }
    }
  }
}

Treat new_transaction_count > 0 as your cue to re-read /accounts/{id}/transactions for that connection. Optional fields on this payload are omitted entirely rather than sent as null — check for a key’s presence, don’t compare it to null. That applies to current_balance, available_balance, and realized_capabilities alike. Which of them show up depends on the source:

Field	Present on
`current_balance`	Finicity and MX. Never on FDE.
`available_balance`	MX only.
`realized_capabilities`	All three sources.

client_id on this event is the same cli_ id you get back from GET /v3/clients — use it directly on any client-scoped endpoint. The key is omitted entirely when the owning client cannot be resolved, so treat it as optional rather than assuming it is always present. account.refresh.failed replaces the balances with a failed_at and an error (same shape as HTTP error responses, including code, type, and category):

account.refresh.failed

{
  "type": "account.refresh.failed",
  "data": {
    "account": {
      "id": "acc_FINICITY_889201",
      "connection_id": "con_FINICITY_41294",
      "source": "FINICITY",
      "failed_at": "2026-07-07T14:22:05Z",
      "error": {
        "code": "institution_unavailable",
        "type": "api_error",
        "category": "INSTITUTION_ERROR"
      }
    }
  }
}

statement.available carries data.statement. It fires once, the first time a statement PDF is stored for a connected account:

statement.available

{
  "event_id": "evt_...",
  "type": "statement.available",
  "created_at": "2026-07-27T14:22:05Z",
  "api_version": "2026-05-22",
  "livemode": false,
  "data": {
    "statement": {
      "id": "stmt_FINICITY_9911",
      "account_id": "acc_FINICITY_110040",
      "connection_id": "con_FINICITY_41300",
      "client_id": "cli_01K9YTQ8V3E7WJ4M2N6RB0XZAD",
      "source": "FINICITY",
      "statement_date": "2026-06-30",
      "download_url": "/v3/statements/stmt_FINICITY_9911/download?client_id=cli_01K9YTQ8V3E7WJ4M2N6RB0XZAD"
    }
  }
}

download_url already includes the /v3 prefix, so join it to the API host (https://api-sandbox.ledgersyncappv2.com), not to the /v3-inclusive base URL you use elsewhere — concatenating it onto the base URL yields /v3/v3/... and 404s. It returns the PDF bytes and needs the read:statements scope. Fetch it on receipt rather than storing it: it is derived from the ids, not a signed link.

This is a save-time event. Balances and transaction counts are extracted later by OCR and are deliberately absent from the payload. If you need the extracted figures, poll the statement after receiving this event.

Two fields are optional and omitted rather than sent as null:

statement_date is absent when the date could not be determined from the document.
client_id is absent when the owning client cannot be resolved — and download_url is omitted with it, because that route is client-scoped.

A re-pull of a statement you already received does not fire this event again. It fires only on first storage.

Next steps

Connection lifecycle

How connections move through initiated, active, failed, and disconnected.

Connect a bank

The full linking flow, from institution search to a canonical connection id.

Errors

The error envelope, status codes, and how to branch on code.

Testing

Sandbox banks and credentials to drive every event end-to-end.

Get started

Guides

Go live

Event catalog

Delivery shape

Verify the signature

Retries and idempotency

Ordering

Test-fire a delivery

`connection.capability_changed` in depth

Hysteresis: no flapping

Payload

Other payload shapes

Next steps

Connection lifecycle

Connect a bank

Errors

Testing

​Subscribe

​Event catalog

​Delivery shape

​Verify the signature

​Retries and idempotency

​Ordering

​Test-fire a delivery

​connection.capability_changed in depth

​Hysteresis: no flapping

​Payload

​Other payload shapes

​Next steps

Connection lifecycle

Connect a bank

Errors

Testing

Subscribe

Event catalog

Delivery shape

Verify the signature

Retries and idempotency

Ordering

Test-fire a delivery

`connection.capability_changed` in depth

Hysteresis: no flapping

Payload

Other payload shapes

Next steps