Webhooks

Instead of polling, you can have Sahl post an event to your server when a call finishes. Webhooks are optional. Every KYC event is sent after the call’s database commit, in the background, so your API response never waits for your endpoint and never fails because of it.

Register an endpoint

In the console open Settings, then Webhooks, then Add Webhook.

Enter the Endpoint URL. It must be https and resolve to a public address. Private, loopback and cloud metadata addresses are refused, both when you save and again before every send. Redirects are not followed.
Choose the events (below).
Save. If you did not supply your own secret (16 characters or more), Sahl generates one, shown once, in the form whsec_ followed by 48 characters. Copy it.
Click Test on the endpoint. Sahl posts a test.ping event to your URL, signed like a real delivery, and shows the status your server answered. The test payload is not shaped like a KYC event (see Test ping).

Endpoint management needs the tenant admin or API manager role. Webhook endpoints are managed in the console, not through the Partner API.

Events

Only calls that carry a reference emit events, because an event names a case. A call without a reference stores nothing and emits nothing.

Event	Sent after	Notes
`kyc.documents_read`	`POST /v1/kyc/extract`
`kyc.case_verified`	`POST /v1/kyc/verify`
`kyc.case_assessed`	`POST /v1/kyc/assess`	Instead of `case_verified`. `/assess` sends one event.
`kyc.eid_completed`	The first `GET /v1/kyc/eid/{key}` that sees a finished check	Later polls send nothing. Two polls racing on the very first observation can both send one.

Events are sent for both environments. The payload says which.

Payloads

Every payload has these four keys.

Key	Type	Meaning
`event`	string	The event name.
`event_id`	uuid	A new id for each event. The same event re-delivered keeps its `event_id`.
`occurred_at`	string	ISO 8601 time with offset, when Sahl built the event.
`tenant_id`	uuid	Your workspace id.

Payloads carry ids, your reference, the environment and a verdict summary. They never carry a field value, a name, a date of birth or any document content: deliveries are stored on Sahl’s side and sent to a URL you typed in.

`kyc.documents_read`

{
  "event": "kyc.documents_read",
  "event_id": "0b6f1c1e-0000-4000-8000-000000000000",
  "occurred_at": "2026-10-07T12:00:00+00:00",
  "tenant_id": "00000000-0000-4000-8000-000000000000",
  "case_id": "00000000-0000-4000-8000-000000000001",
  "reference": "client-0001",
  "environment": "sandbox",
  "document_ids": ["22222222-2222-4222-8222-222222222222"],
  "reader_unavailable": false,
  "failed_checks": []
}

failed_checks holds the ids of failed checks with severity critical or warning, without duplicates.

`kyc.case_verified` and `kyc.case_assessed`

{
  "event": "kyc.case_assessed",
  "event_id": "0b6f1c1e-0000-4000-8000-000000000002",
  "occurred_at": "2026-10-07T12:01:00+00:00",
  "tenant_id": "00000000-0000-4000-8000-000000000000",
  "case_id": "00000000-0000-4000-8000-000000000001",
  "reference": "client-0001",
  "environment": "sandbox",
  "verdict": {
    "status": "passed",
    "failed_checks": ["completeness"],
    "risk_level": "Low",
    "suitability": "Suitable"
  }
}

`verdict` key	Meaning
`status`	`passed` or `failed`, the verdict’s `passed`.
`failed_checks`	Ids of failed critical and warning checks. A screening id is cut to its kind (`screening:sanctions`, `screening:pep`) so no person’s name leaves Sahl.
`risk_level`	`kyc.case_assessed` only. The compliance risk level: `Low`, `Medium` or `High`.
`suitability`	`kyc.case_assessed` only. The suitability sentence.

`kyc.eid_completed`

{
  "event": "kyc.eid_completed",
  "event_id": "0b6f1c1e-0000-4000-8000-000000000003",
  "occurred_at": "2026-10-07T12:30:00+00:00",
  "tenant_id": "00000000-0000-4000-8000-000000000000",
  "key": 123456,
  "reference": "client-0001",
  "complete": true,
  "passed": true,
  "failed_checks": []
}

complete is false when the request ended archived without the client finishing. failed_checks holds the failed critical eID check ids.

Test ping

The Test button sends a different shape, signed the same way:

{
  "event_type": "test.ping",
  "timestamp": "2026-10-07T12:00:00+00:00",
  "data": { "message": "This is a test ping from Sahl", "webhook_id": "...", "tenant_id": "..." }
}

Its header X-Sahl-Event is test.ping. It has no event or event_id key, so route on the header, not on a key. It carries no X-Sahl-Delivery header, waits 10 seconds for your answer, and counts any status below 400 as a success (real deliveries need a 2xx and wait 30 seconds).

Request headers

Header	Value
`Content-Type`	`application/json`
`X-Sahl-Event`	The event name.
`X-Sahl-Delivery`	A unique id per delivery. Stays the same across retries of one delivery.
`X-Sahl-Timestamp`	Unix seconds when this attempt was signed.
`X-Sahl-Signature-V2`	`sha256=` plus the hex HMAC-SHA256 of `"<timestamp>.<raw body>"`.
`X-Sahl-Signature`	`sha256=` plus the hex HMAC-SHA256 of the raw body alone. Kept for old receivers. It cannot stop a replay.

Verify the signature

Read the raw body bytes before you parse the JSON. Re-serialised JSON does not match.
Compute HMAC-SHA256(secret, timestamp + "." + body) and compare with X-Sahl-Signature-V2 in constant time.
Reject a timestamp more than a few minutes from your clock (the code below uses 5 minutes, which is your choice, not a Sahl rule). Each retry is signed again, so its timestamp is fresh.

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

// rawBody: the request body exactly as received (Buffer or string).
// headers: lowercase header names, as Node and Express give them.
export function verifySahlWebhook(rawBody, headers, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
  const timestamp = headers["x-sahl-timestamp"];
  const received = headers["x-sahl-signature-v2"];
  if (!/^\d+$/.test(timestamp ?? "") || !received) return false;
  if (Math.abs(nowSeconds - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const expected =
    "sha256=" + createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

import hashlib, hmac, time

TOLERANCE_SECONDS = 300


def verify_sahl_webhook(raw_body: bytes, headers: dict, secret: str, now: float | None = None) -> bool:
    """raw_body is the request body exactly as received. headers keys are lowercase."""
    timestamp = headers.get("x-sahl-timestamp", "")
    received = headers.get("x-sahl-signature-v2", "")
    if not timestamp.isdigit() or not received:
        return False
    if abs((now or time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received, expected)

A receiver in Express. express.raw keeps the bytes.

import express from "express";
import { verifySahlWebhook } from "./verify.mjs";

const app = express();
const seen = new Set(); // use a database table in production

app.post("/sahl/webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifySahlWebhook(req.body, req.headers, process.env.SAHL_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body.toString("utf8"));
  const id = req.headers["x-sahl-delivery"];
  if (!seen.has(id)) {
    seen.add(id);
    // handle event.event, event.reference, event.case_id ...
  }
  res.status(204).end(); // any 2xx counts as delivered
});

app.listen(3000);

Both functions above were run against the code that signs real deliveries: a valid delivery verifies, a changed body fails, and a stale timestamp fails.

Delivery and retries

Item	Value
Success	Any HTTP status from 200 to 299.
Timeout	30 seconds by default.
Redirects	Not followed. A 3xx is a failure.
Attempts	6 in total, the first included.
Waits after a failed attempt	1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours.
After the 6th failure	The delivery stays `failed` for good.
Guarantee	At least once. The same event can arrive more than once.
Order	Not guaranteed.

The first attempt is made right after the call. Later attempts are made by a retry job that runs every few minutes, so a retry can come slightly after its scheduled time. An endpoint that you switch off keeps its due deliveries and resumes them when you switch it back on. Make your handler idempotent. De-duplicate on X-Sahl-Delivery (one id per delivery) or on event_id (one per event). Answer fast with a 2xx and do the work after. The console shows every delivery of an endpoint with its HTTP status and attempt count, and keeps up to 2,000 characters of your response body.

Troubleshooting

Symptom	Cause
Signature never matches	You verified parsed JSON, not the raw bytes. Or the secret is not the endpoint’s secret.
Signature matches only sometimes	Your clock is off by more than your tolerance.
No event arrives	The call had no `reference`; the endpoint is not subscribed to that event; the endpoint is switched off.
Console says “Refused, not sent”	Your URL resolves to a private or metadata address, or is not https.
An event arrived twice	Normal. De-duplicate.

Start

Bank connections and open banking

Documents (OCR)

Verification and eID

Risk assessment and scoring

Build

Reference

Console only

Register an endpoint

Events

Payloads

`kyc.documents_read`

`kyc.case_verified` and `kyc.case_assessed`

`kyc.eid_completed`

Test ping

Request headers

Verify the signature

Delivery and retries

Troubleshooting

​Register an endpoint

​Events

​Payloads

​kyc.documents_read

​kyc.case_verified and kyc.case_assessed

​kyc.eid_completed

​Test ping

​Request headers

​Verify the signature

​Delivery and retries

​Troubleshooting

Register an endpoint

Events

Payloads

`kyc.documents_read`

`kyc.case_verified` and `kyc.case_assessed`

`kyc.eid_completed`

Test ping

Request headers

Verify the signature

Delivery and retries

Troubleshooting