How-to12 min read

How to Set Up Bank Transaction API Webhooks

Editorial Team
Content Writer
How to Set Up Bank Transaction API Webhooks

Last Updated: 17 November 2026

Quick Summary

Bank transaction webhooks are HTTP callbacks that a bank data provider pushes to a URL you control the moment a transaction event occurs, so your application listens instead of polling on a schedule. Setup means registering an HTTPS callback URL with narrow event subscriptions, verifying the signature on the raw request body, returning a 2xx response quickly, and processing the queued work asynchronously.

  • Polling wastes quota and leaves a gap between a change and its discovery; webhooks close that gap to seconds.
  • Your callback URL must be HTTPS, publicly resolvable and stable, with a tenant identifier in the path.
  • Verify the signature against the raw request body before parsing JSON, and reject stale timestamps.
  • Make processing idempotent on the event identifier, because at-least-once delivery means duplicates are the contract.
  • Run a scheduled reconciliation sweep to catch any transaction that delivery attempts missed.
Ready to see bank webhooks in action?Connect a UK or EU bank read-only and watch transactions arrive in Sheets, your app or Claude.
Connect a UK bank

Bank Transaction API Webhooks Setup: How Transaction Notifications Work

A webhook is an HTTP callback that a bank data provider sends to a URL you control the moment a transaction event occurs, and bank transaction webhooks are the mechanism behind it. Instead of asking for updates on a schedule, your application listens, and the provider pushes a signed POST request to your endpoint within seconds of a status change.

Bank connections of this kind generally follow the same pattern: a consent, a subscription, and a stream of transaction notifications. Below, we will show you exactly how to register an endpoint, verify signatures, survive retries, and reconcile what arrives against what your ledger expects.

The first thing most guides get wrong is treating a webhook as a notification that a transaction happened. It is not. A webhook is a notification that something about a transaction changed, and the payload carries the identifier you use to fetch the authoritative record. Hold that distinction and the rest of the implementation falls into place.

Diagram illustrating how bank transaction webhooks relay data from an API to a developer's code editor.
Diagram illustrating how bank transaction webhooks relay data from an API to a developer's code editor.

Webhook vs Polling a Transactions API

Polling asks "has anything changed?" on a timer. Webhooks wait to be told. For a transactions API, polling a balance or statement endpoint every few minutes wastes quota and still leaves a gap between the change and your discovery of it. Webhooks close that gap to seconds and let you reserve polling for reconciliation sweeps rather than primary ingestion.

The trade-off is operational. A polled endpoint fails loudly when your scheduler stops. A webhook endpoint can fail silently if your listener is down and the provider's retries run out. That is why mature integrations run both: webhooks for real-time updates, and a scheduled reconciliation pass to catch anything the delivery attempts missed.

If you are weighing how often to import transactions at all, how to choose bank transaction import frequency options sets out the trade-offs between latency, quota and reconciliation effort.

Registering Your Endpoint and Choosing Event Types

Registration is a single API call that binds a callback URL to a set of event types. You send the endpoint URL, the events you want, and usually a description or secret; the provider returns a subscription identifier you store against the tenant or bank connection it belongs to. Get this wrong and you will receive every event for every customer at one URL, which is a privacy problem before it is an engineering one.

Choose event types narrowly. A typical bank data feed exposes transaction created, transaction updated, transaction deleted, balance updated, and consent or connection status events. Subscribe to the transaction events you actually process, plus connection status so you can react when a consent expires. Blanket subscriptions to everything are the most common cause of noisy, unprocessable traffic.

Configuring the Callback URL and Subscriptions

Your callback URL must be HTTPS, publicly resolvable, and stable. Do not point it at a laptop; use a tunnel or a staging environment during development. Include a tenant identifier in the path or query string so one listener can route events to the right customer record without inspecting the body first.

  • Use a dedicated path such as /webhooks/bank-transactions/{connectionId}
  • Return 2xx within a few seconds and queue the work
  • Never do heavy processing before responding
  • Log the raw request body before parsing it

Keep subscriptions narrow and the callback URL stable, and the rest of the setup follows.

Item Requirement Note
Callback URL HTTPS, publicly resolvable, stable Use a tunnel or staging environment during development
Path Dedicated path with tenant identifier Example: /webhooks/bank-transactions/{connectionId}
Event types Transaction created, updated, deleted Subscribe only to events you actually process
Connection events Consent or connection status Lets you react when a consent expires
Response Return 2xx within a few seconds Queue the work, never process heavily before responding
Logging Log the raw request body Log before parsing it

Bank Transaction API Webhooks Setup Example: Receiving a POST Request

The endpoint itself is small. Your listener accepts a POST, reads the raw body, verifies the signature against that raw body, parses JSON, and enqueues a job. Here is the shape in a Node/Express handler:

app.post('/webhooks/bank-transactions/:connectionId',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('X-Signature');
    if (!verify(req.body, signature, process.env.WEBHOOK_SECRET)) {
      return res.status(401).send('invalid signature');
    }
    const event = JSON.parse(req.body.toString('utf8'));
    queue.push({ connectionId: req.params.connectionId, event });
    res.status(200).send('ok');
  });
Four details decide whether this works in production. Read the **raw request body** before any JSON middleware touches it, because signature verification runs over bytes, not parsed objects. Verify before you parse. Respond `200` fast and process asynchronously. And treat the payload as a pointer, not a record: take the event identifier and transaction identifier, then fetch the full transaction from the API so you are never reconciling against a truncated body.

The same pattern maps to Python, Go or PHP without change in structure. The event destination is your handler; the request body is the envelope; the HTTP response is the acknowledgement.

## Bank Transaction Webhook Security: Signatures, Secrets and TLS

Signature verification is the only thing standing between your endpoint and forged transaction events. The provider signs the raw payload with a shared secret key, usually an HMAC over the body and a timestamp header, and you recompute it and compare in constant time. Reject anything that fails, and reject stale timestamps to blunt replay attacks.

- Serve the endpoint over TLS only and reject plain HTTP at the edge
- Store the secret in a secrets manager, never in source control
- Rotate secrets on a schedule and support two active secrets during rotation
- Compare signatures with a constant-time function
- Never trust an access token or authorisation header alone as proof of origin

Bank transaction webhook security is also a data-minimisation question. Log event identifiers and status codes, not full payloads containing account numbers. If you want the wider picture of how read-only access is protected end to end, [7 things to know about read-only open banking security](/blog/read-only-open-banking-security) covers the consent and access model behind the signature.

## Plaid Webhooks and Provider-Neutral Patterns

Plaid's webhook model is a useful reference because it exposes the pattern most providers converge on: you register a webhook URL per item, Plaid sends a verification request you must answer, and subsequent events carry a `webhook_type` and `webhook_code` you switch on. The lesson is not the specific field names, it is that every provider has a registration step, a verification handshake, and an event taxonomy.

Build provider-neutral from day one. Normalise incoming events into your own internal shape, an event identifier, a connection identifier, a transaction identifier, a status change and a timestamp, and keep provider-specific parsing in one adapter layer. When you add a second bank or a second provider, only the adapter changes.

If you are building on a REST API and want the foundational read patterns before layering webhooks on top, [how do you get bank transaction data via REST API](/blog/how-to-get-bank-transaction-data-via-rest-api) walks through the request and response cycle.

## Webhook Retry and Duplicate Event Handling

Retries are guaranteed, and so are duplicates. Providers retry failed deliveries with backoff, and network ambiguity means the same event can arrive twice even when you responded successfully. Webhook retry and duplicate event handling therefore reduces to one rule: make your processing idempotent on the event identifier.

- Store every processed event identifier with a unique constraint
- On receipt, attempt the insert; if it conflicts, acknowledge and skip
- Make downstream writes idempotent on the transaction identifier too
- Handle out-of-order delivery by comparing timestamps, not arrival order
- Set a timeout on your own outbound calls so a slow dependency does not cause a retry storm

Duplicate events are not a bug to report. They are the contract. Design for at-least-once delivery and your reconciliation will stay clean.

## Testing, Monitoring and Reconciling Bank Transaction Webhooks

A webhook integration that is never tested against failure will fail quietly. Use a test environment with a sandbox bank, replay captured payloads into your listener, and deliberately break your endpoint to watch the retry behaviour. Then monitor the things that matter: delivery attempt success rate, acknowledgement latency, signature failures, and the age of the oldest unprocessed event.

Reconciliation closes the loop. Run a scheduled sweep that pulls transactions for the period and compares them against what your webhook pipeline recorded. Any transaction present in the API but absent from your store is a missed delivery; any present in your store but absent from the API is a deletion or a bug. Event ordering matters here, so always resolve the final state from the API rather than from the last event you happened to receive.

## Connecting Your First Bank Account in Zenith

The fastest way to see this pattern working is to connect an account and watch the events arrive. [Connect any UK bank to Zenith](/bank-sync/gb) through the bank's own PSD2 consent flow, choose the accounts to sync, and Zenith keeps balances and transactions current without you building a single bank integration.

If you need to make the commercial case before you connect, [how to justify bank API costs to your finance director](/blog/how-to-justify-bank-api-costs) lays out the comparison against manual CSV handling.

---

The hard part of bank transaction API webhooks setup is not the handler, it is the operational discipline around it: narrow subscriptions, verified signatures, idempotent processing, and a reconciliation sweep that catches what delivery missed. That discipline is what separates a feed you trust from one you end up chasing.

Zenith handles the bank connectivity layer so your team can focus on the processing layer. Authenticate through your bank's consent flow, and Zenith keeps statements, balances and transactions up to date across 2,400+ banks in 30 European countries, with read-only access and GDPR compliance.

Get started with Zenith and put a European bank feed behind your product.
<section style="margin:3rem 0 2rem 0;" itemscope itemtype="https://schema.org/FAQPage"><h2 style="font-weight:700; margin:0 0 4px 0;">Frequently Asked Questions</h2><div style="padding:20px 0; border-bottom:1px solid #e5e7eb;" itemscope itemprop="mainEntity" itemtype="https://schema.org/Question"><h3 style="font-weight:600; margin:0 0 8px 0;" itemprop="name">How do you set up webhooks for a bank transaction API?</h3><div style="line-height:1.7;" itemscope itemprop="acceptedAnswer" itemtype="https://schema.org/Answer"><p itemprop="text" style="margin:0;">Register an HTTPS endpoint with the provider, choose the transaction and payment event types you need, then store the signing secret securely. Your endpoint should accept POST requests, verify the signature, return a 2xx status code quickly, and process the payload asynchronously. Test in a sandbox first, then promote the same endpoint configuration to production and monitor delivery logs for failures.</p></div></div><div style="padding:20px 0; border-bottom:1px solid #e5e7eb;" itemscope itemprop="mainEntity" itemtype="https://schema.org/Question"><h3 style="font-weight:600; margin:0 0 8px 0;" itemprop="name">What information does a bank transaction webhook send?</h3><div style="line-height:1.7;" itemscope itemprop="acceptedAnswer" itemtype="https://schema.org/Answer"><p itemprop="text" style="margin:0;">A typical payload includes an event identifier, event type, timestamp, the connected account reference, and the transaction details: amount, currency, booking date, counterparty name and a transaction status. Many providers send a thin notification containing only IDs, so you fetch the full record from the API. Treat the payload as a trigger and confirm the final transaction status from the API before writing to your ledger.</p></div></div><div style="padding:20px 0; border-bottom:1px solid #e5e7eb;" itemscope itemprop="mainEntity" itemtype="https://schema.org/Question"><h3 style="font-weight:600; margin:0 0 8px 0;" itemprop="name">How should an application handle duplicate webhook events?</h3><div style="line-height:1.7;" itemscope itemprop="acceptedAnswer" itemtype="https://schema.org/Answer"><p itemprop="text" style="margin:0;">Make processing idempotent. Store each event identifier and skip anything already seen. Use the transaction identifier as an upsert key so a repeated delivery updates the same record rather than creating a second one. Return a 2xx response for duplicates so the provider stops retrying, and log the duplicate for reconciliation. This matters because webhook retry and duplicate event handling is normal behaviour, not an edge case.</p></div></div><div style="padding:20px 0; border-bottom:1px solid #e5e7eb;" itemscope itemprop="mainEntity" itemtype="https://schema.org/Question"><h3 style="font-weight:600; margin:0 0 8px 0;" itemprop="name">How do you test bank transaction webhooks before going live?</h3><div style="line-height:1.7;" itemscope itemprop="acceptedAnswer" itemtype="https://schema.org/Answer"><p itemprop="text" style="margin:0;">Use the provider&#039;s sandbox and a local tunnel to expose your development server over HTTPS. Trigger test events for each subscription, confirm signature verification passes and fails correctly, and simulate timeouts and duplicate deliveries. Check that your endpoint responds within the provider&#039;s timeout window, that failed events land in a retry queue, and that your reconciliation job catches anything missed before switching to production.</p></div></div></section>
FAQ

Frequently asked questions

Stop pasting. Start asking.

One read-only connection to 2,400 European banks, set up in about five minutes. Your transactions land in Google Sheets, Claude or your own app.

5 € per account a month · Cancel any time