Webhooks developer reference

BankSync delivers synced bank data to your endpoint as signed JSON POST requests. This reference documents the wire format so you can build and verify a receiver. To connect an endpoint and create a feed, see the Webhooks integration guide.

The envelope#

Every delivery is a single JSON object:

{  "id": "evt_job-abc_0_1_2",  "type": "transactions.delta",  "apiVersion": "2026-06-01",  "createdAt": "2026-06-01T09:30:00.000Z",  "workspaceId": "ws_...",  "feed": { "id": "feed_...", "name": "Chase to Webhook", "dataType": "transactions" },  "job": { "id": "job_abc", "trigger": "scheduled" },  "batch": { "sequence": 3 },  "data": [    /* rows: see the per-type schemas below */  ]}

Event types#

Signing & verification#

BankSync signs every delivery using the Standard Webhooks format, so existing verifier libraries work out of the box. Each request carries:

webhook-id:        evt_job-abc_0_1_2webhook-timestamp: 1718270000webhook-signature: v1,g0Q1...base64...==content-type:      application/jsonuser-agent:        BankSync-Webhooks/1.0 (+https://banksync.io/docs/api/webhooks-reference)

The signature is HMAC-SHA256 over the string {webhook-id}.{webhook-timestamp}.{body}, base64-encoded, keyed by the base64-decoded payload of your whsec_ secret. During a secret rotation the header carries two space-separated signatures (current + previous); a delivery is valid if either verifies.

Verify with the Standard Webhooks library for your language:

// Node (npm i standardwebhooks)import { Webhook } from 'standardwebhooks'
const wh = new Webhook(process.env.BANKSYNC_WEBHOOK_SECRET) // "whsec_..."app.post('/webhooks/banksync', express.raw({ type: 'application/json' }), (req, res) => {  let event  try {    event = wh.verify(req.body, {      'webhook-id': req.header('webhook-id'),      'webhook-timestamp': req.header('webhook-timestamp'),      'webhook-signature': req.header('webhook-signature'),    })  } catch {    return res.sendStatus(400) // bad signature  }  // De-dupe on event.id, then process event.data …  res.sendStatus(200)})

# Python (pip install standardwebhooks)from standardwebhooks import Webhook
wh = Webhook(os.environ["BANKSYNC_WEBHOOK_SECRET"])  # "whsec_..."
@app.post("/webhooks/banksync")def banksync_webhook():    try:        event = wh.verify(request.data, dict(request.headers))    except Exception:        return ("", 400)    # De-dupe on event["id"], then process event["data"] …    return ("", 200)

Respond with any 2xx to acknowledge. Non-2xx responses are retried (see below).

Retries & delivery#

Delivery is at-least-once. BankSync retries transient failures with exponential backoff:

Because delivery is at-least-once and retries reuse the same id, deduplicate on id (or webhook-id). Within a job, batch.sequence lets you order batches. An endpoint that fails persistently is auto-disabled; re-enable it from the endpoint page after fixing your server.

Per-data-type payloads#

Rows are camelCase; money is JSON numbers (parse with a decimal type); dates are ISO 8601 (or YYYY-MM-DD for date-only fields); currency is ISO 4217. Optional fields are omitted when absent. Enrichment-added custom fields are nested under a custom object. Field availability varies by provider (Plaid / Fiskil / SaltEdge / SnapTrade).

transactions.delta#

balances.snapshot#

holdings.snapshot#

trades.snapshot#

orders.snapshot#

loans.snapshot#

The widest schema; almost every field is optional and provider/product-dependent. Core fields: id, accountId, loanType, loanName, currentBalance, originalAmount, interestRate, minimumPaymentAmount, nextPaymentDueDate, isOverdue, currency, bankId. Product-specific groups:

• Credit cards: aprPurchase, aprCash, aprBalanceTransfer, lastStatementBalance, lastStatementDate.
• Student loans: disbursementDates (array), pslfStatus, repaymentPlan.
• Mortgages: escrowBalance, hasPMI, hasPrepaymentPenalty, propertyAddress (object), loanTerm, maturityDate.

Idempotency & ordering checklist#

• Deduplicate on id.
• For transactions.delta, upsert by data[].id.
• For snapshots, replace state by the documented identity key when sync.completed arrives.
• Reject webhook-timestamp older than 5 minutes.
• Don't require auth on the receiving route; verify the signature instead.