Skip to main content

Check the token or trust the call: verifying signature webhooks

· 4 min read
Julien Jenoudet
Julien Jenoudet
CEO of IgniSign

Your product has a new flow: a user signs a mandate inside your app, and the moment the signature is done your backend activates the account, releases the file or moves the deal forward. That moment arrives as a webhook. The decision every integrating developer faces is simple to state: does your handler act on any call that reaches the endpoint, or does it first confirm that the call really came from IgniSign?

Why the endpoint alone is not enough​

A webhook endpoint is a public URL. Anyone who learns it, or guesses its shape, can post a JSON body that looks like a "signature request completed" event. If your handler trusts the body, a forged call can unlock exactly the step the signature was meant to protect. An auditor who later asks how you knew the user had signed will not accept "a request hit our URL".

Common shortcuts are a secret path segment or an allowlist of source addresses. Both depend on things that change or leak: URLs end up in logs and tickets, and network ranges are not part of the API contract. Neither ties a given event to a given application and environment.

What each IgniSign webhook carries​

Every event IgniSign sends includes three fields alongside the topic and action: appId, appEnv and a verificationToken. The token is specific to that delivery. Your backend sends it back to the IgniSign API, together with the application id and environment, and gets an answer: this event is genuine, or it is not.

With the Node SDK, the check is one call:

const isValid = await ignisign.client.tokensV4.checkConsumeWebhook({
  token: verificationToken,
  appId,
  appEnv,
});

if (!isValid) {
  return res.status(401).end();
}

Only after that answer does your handler change state. The SDKs also give you a typed callback registration for events, so the check sits in one place rather than in every handler.

The trade-off, stated plainly​

Checking the token costs one extra API call per event and a dependency on that call succeeding. Trusting the call costs nothing at runtime and moves the risk into your business logic, where it is hardest to see.

For a flow where the webhook only refreshes a status badge, the cost of a forged event is small, and you might decide the check can wait. For a flow where the webhook releases money, access or a document, the check is the step that turns "we received a message" into "IgniSign told us this signature happened". The level of signature does not change this: a simple electronic signature on a low-risk consent and an advanced signature with SMS authentication both reach your backend through the same event, and both deserve a handler that knows the event is real.

Make the handler safe to run twice​

Verification answers "is this real". A second question is "what if it arrives again". IgniSign keeps an event log for your application, and you can resend an event from it by hand. That is useful when your endpoint was down during a deploy. It also means your handler may see the same event more than once.

So key your state change on the signature request id, not on the arrival of a message. If the account is already active, a second verified "completed" event is a no-op. If your endpoint was unavailable, nothing is lost: find the event in the log, resend it, and the same code path picks it up.

A short checklist​

  • Subscribe only to the topics your flow uses; webhooks are controlled per topic.
  • On every event, confirm the verificationToken with the API before touching state.
  • Reject events whose appEnv does not match the environment the handler serves, so a development event never moves a production record.
  • Make the state change idempotent on the signature request id.
  • When your endpoint misses events, use the event log and resend them manually.

The decision​

If the webhook unlocks something your user or your auditor cares about, check the token on every event. It is one call, it ties each event to your application and environment, and it gives your product a clear answer to "how do you know this was signed". Then fetch the proof you keep: the signed file, the proof page and the audit log are there when someone asks.