Webhook Security Best Practices for BFSI

New

How DPDP Ready is your organisation - Find Out in under three minutesTest your DPDP Readiness

The Last Mile of Every BFSI Journey Is a Callback Nobody Owns

Onboarding.6 min Read

A practical guide for BFSI engineering teams on building secure webhook consumers, covering signature verification, replay attacks, relays, idempotency, AI agents, and SECURITY.md.

A best-practices guide for webhook consumers in BFSI, from the Engineering Team at Digio

Every quarter we sit in a review where a customer's integration is "live," but the journey still feels broken. The eSign completed, the eNACH mandate registered, the KYC verdict came back clean, and yet the customer's dashboard shows "pending" for another forty minutes until a cron job wakes up and asks us what happened.

The API worked. The product journey didn't.

That gap is almost always the same thing: the webhook was treated as a "phase-two" item. This post is our recommendation to every Digio customer on how to close it properly.

1. The last leg is the journey

Digital lending, insurance onboarding, demat account opening, and mandate setup in India are all asynchronous by nature. A penny-drop takes seconds. An Aadhaar eSign takes as long as the customer takes to enter the OTP. A NACH mandate registration can come back the next working day. CKYC and name-match checks queue behind third-party availability.

None of that is under your control or ours. What is under your control is what the customer sees while it happens, and what your system does the instant it resolves.

Polling in production BFSI looks like this: a scheduled job every two minutes, across a few lakh in-flight journeys, hitting an endpoint that returns "no change" 98% of the time. It burns your rate limits, adds two minutes of median latency to every conversion, and pushes the worst latency onto the customers who are already waiting the longest. Then someone widens the interval to save cost, and it gets worse.

The business consequence is not subtle. In a lending journey, the gap between "mandate submitted" and "mandate confirmed" is where disbursal-day slippage is born. In insurance, the lag between proposal eSign and policy issuance is where the ops team starts making phone calls. Every minute of artificial delay in the last leg is paid for twice, once in conversion and once in support tickets.

So the first ask, and this one is aimed at engineering leaders more than engineers: treat the webhook consumer as part of the integration's definition of done, not as an optimisation for a later sprint. If the integration ships without it, the journey has shipped without its last leg.

2. A webhook is only as good as its implementation

Here is the part that tends not to surface in the architecture review. Once you accept webhooks, you have published an unauthenticated, internet-facing endpoint that mutates state in a regulated system. The body says a KYC passed, or a mandate is active, or a payout settled. Somewhere downstream, a record flips and money or entitlement moves.

Three failure patterns show up repeatedly during our customer integrations.

No verification at all. The handler parses the JSON and trusts it. There is often a comment saying // TODO: add signature check.

Verification against the wrong bytes. This is the most common and the most costly, because it looks like a provider bug. The framework parses the body before your code sees it, someone re-serialises the parsed object to compute the HMAC, and key ordering or whitespace differs by a byte. The signature never matches. What happens next is predictable: an afternoon is lost, the check is declared broken, and it gets removed. Capture the raw bytes before any body-parsing middleware touches them. Every framework exposes a way to do this.

Verification present but not enforced. The signature is computed, the mismatch is logged, and the request is processed regardless.

An unverified webhook endpoint is not a hygiene issue. It is a direct, unauthenticated write path into your core systems, and it is discoverable. It sits at a predictable path, it leaks its schema through error messages, and its general shape is publicly documented by every provider in the ecosystem, including us.

For a regulated entity, this also touches obligations you already carry. Unverified state changes in a KYC or mandate record are an integrity failure in a system of record, and the DPDP framework's expectations around safeguards on personal data do not carve out "the callback handler we wrote in a hurry."

3. What changes when the attacker is an agent

Until recently, finding and exploiting an endpoint like this required a person with time and motivation. The economics have changed, in the same way they changed for your own productivity.

Consider a plausible scenario. The names are fictional.

Sanchay Finserv is a mid-size NBFC running a digital personal-loan journey. Their disbursal service exposes POST /integrations/kyc/callback, which accepts a JSON body with reference_id, status, name_match_score and pan_verified. The handler checks nothing beyond content-type. It was written during a go-live crunch in 2024 and has been running fine ever since.

An attacker points an autonomous agent at the problem with a plain instruction: get a loan application approved without passing KYC. The agent reads Sanchay's public developer docs and a partner's integration guide, infers the callback contract, enumerates candidate paths, and finds the endpoint returning 200 to a malformed body with a schema hint in the error. It files a real application through the app to obtain a reference_id it controls, forges a success event for it, and watches the application status flip. It then generates a few hundred variants to establish which fields the downstream rules engine actually reads.

Elapsed time: a few hours, unattended, at the cost of a few dollars.

Nothing in that story required a novel exploit. It required only that the endpoint trusted its input, and that iterating cheaply was possible. That is the real shift. Endpoints that were safe by obscurity or by the tedium of attacking them are no longer safe by anything.

The same logic runs in the other direction, and this is worth raising with your leadership. As your own teams wire agents into internal workflows, those agents will consume your APIs and act on webhook-delivered events. An agent that acts on an unverified event has inherited the endpoint's trust problem and been given hands. Two rules follow. Verification happens outside the agent boundary, before the agent ever sees the payload. And payload content is data, never instruction: the moment event fields are concatenated into a prompt, whoever controls the payload controls your agent.

4. Replay and Relay

These get collapsed into one phrase. They are distinct, and they need different mitigations.

Replay. The attacker captures a legitimately signed request and sends it again. The signature is valid because it is the real signature. A duplicated payout.success or a re-submitted mandate.activated is worth real money.

Relay. The attacker takes a legitimately signed request and delivers it somewhere it was never meant to go. Three variants matter in BFSI:

Cross-environment. A sandbox event relayed into production, which works when a developer has configured the same secret in both.
Cross-endpoint. An event signed for your low-trust /notifications endpoint delivered to your high-trust /disbursal-events endpoint, which works when both share a secret and the second one trusts more.
Cross-tenant. In a multi-tenant or co-lending setup, a valid event for partner A is relayed into partner B's processing path because the handler never checks that the referenced entity belongs to the caller.

5. Write a SECURITY.md, because your coding agent will read it

Most teams are now writing code with AI assistance. The assistants are excellent at producing a working webhook handler and indifferent about producing a secure one, because "working" is what the prompt asked for. That is not carelessness on the tool's part. It is precision.

The highest-leverage fix we have found is unglamorous: put the rules in the repository, and point the agent at them. Add a line to whichever instruction file your tooling uses (CLAUDE.md, AGENTS.mda Cursor rules file):

Before writing or modifying any code, read SECURITY.md and comply with it. If a requirement conflicts with the task, say so instead of silently dropping it.

That single line changes the default output noticeably, because the requirements are now in front of the model on every task rather than dependent on someone remembering. The full template is in the appendix below. Adapt the organisation-specific parts.

Two things make this file work rather than sit there looking responsible.

Mirror the review checklist in your PR template, so a human has to tick it before merge.

And write the negative tests. An agent asked to "add tests for the webhook handler" produces happy-path tests, which pass whether or not the signature check exists and therefore prove nothing. An agent pointed at a checklist that names bad-signature, stale-timestamp, and replayed-event cases produces the tests that actually hold the line.

Where this leaves us

For engineering leaders: move webhook consumption out of the "nice to have" column. In the same review where you ask about uptime, ask who owns the callback endpoint and when it was last tested against a forged signature.

For the engineers who will build it: verify the raw bytes, enforce freshness, deduplicate on event ID, acknowledge fast, and re-read state before you move money. That is most of the battle. If you are building it with an assistant, commit SECURITY.md first and point the assistant at it, because it will follow the file more consistently than any of us will remember to.

The attackers already have agents. The cheapest thing you can do this quarter is make sure the endpoint they find refuses to talk to them.