Webhooks

​

What it’s for

​

Who can use it

• Everyone in your organization can open the Webhooks page and read the delivery log.
• Admin and Developer can add, edit, test, pause, resume and delete endpoints, and rotate secrets.
• Admin, Reviewer, Analyst and Developer can resend deliveries. Viewer / Auditor can’t.
• Webhooks don’t use credits.

​

Step by step

​

Add an endpoint

1. In the sidebar, under Developer, click Webhooks. The same panel is also in Settings → Developers.
2. Click Add endpoint.
3. In URL, enter a public HTTPS address that accepts POST requests, for example https://api.demobank.co.ke/sentinel/webhook. Private addresses, plain http and URLs with a username or password are refused.
4. In Description, give it a name your team will recognise, for example “Production onboarding service”.
5. Under Events, tick what this endpoint receives. Check completed or failed and AML monitoring alert are ticked by default.
6. Under Products, leave Every product ticked, or untick it and choose from KYC (identity), AML screening, Documents (IDP), Business (KYB) and Liveness.
7. In Checks from, choose Live and test, Live only or Test keys only. Send test-key results to a staging endpoint with Test keys only.
8. Under Custom headers, click Add header if your gateway expects a token, for example Authorization. You can add up to 5. Values are hidden after saving.
9. Click Add endpoint.
10. The Signing secret dialog shows the secret once. Copy it into your secrets manager, tick I’ve stored this secret. and click Done.

​

Check the signature

1. Read the raw request body as bytes, before any JSON parsing.
2. Reject it if X-Sentinel-Timestamp is missing or more than 5 minutes from your clock.
3. Compute HMAC-SHA256 of the timestamp, a full stop and the raw body, with your secret, as lowercase hex.
4. Compare it in constant time with X-Sentinel-Signature-V2, and with X-Sentinel-Signature-V2-Next if present. Accept if either matches.
5. Return any 2xx status within 10 seconds. Do slow work after you respond.

​

Node

// Node 18+, no dependencies. Save as receiver.mjs.
import crypto from "node:crypto";
import http from "node:http";

const SECRET = process.env.SENTINEL_WEBHOOK_SECRET;

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-sentinel-timestamp"];
  if (!timestamp || !/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // replay window
  const expected = Buffer.from(
    crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex"),
  );
  return [headers["x-sentinel-signature-v2"], headers["x-sentinel-signature-v2-next"]]
    .filter((sig) => typeof sig === "string" && sig.length === expected.length)
    .some((sig) => crypto.timingSafeEqual(Buffer.from(sig), expected));
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks);
    if (!verify(rawBody, req.headers, SECRET)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // answer first, then process
    const event = JSON.parse(rawBody.toString("utf8"));
    console.log(event.event, event.scan_id, event.status);
  });
}).listen(3000);

​

Python

import hashlib
import hmac
import os
import time

SECRET = os.environ["SENTINEL_WEBHOOK_SECRET"]

def verify(raw_body: bytes, headers, secret: str = SECRET) -> bool:
    timestamp = headers.get("X-Sentinel-Timestamp", "")
    if not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 300:  # replay window
        return False
    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    given = [headers.get("X-Sentinel-Signature-V2"), headers.get("X-Sentinel-Signature-V2-Next")]
    return any(sig and hmac.compare_digest(sig, expected) for sig in given)

# Flask: verify(request.get_data(), request.headers)
# Django: verify(request.body, request.headers)

​

curl

BODY='{"event":"sentinel.test","scan_id":"test_local","status":"PASS","timestamp":"2026-10-16T09:00:00.000Z","product":null,"result":{"test":true}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SENTINEL_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "X-Sentinel-Timestamp: $TS" \
  -H "X-Sentinel-Signature-V2: $SIG" \
  -d "$BODY"

​

Send a test event

1. On the endpoint’s row, click Send test.
2. Wait for the line under the row. Test delivered: HTTP 200 in … ms. means your receiver accepted it. Test failed: … gives the reason.

​

Read the delivery log

1. Find Deliveries under your endpoints. It lists the latest 100 deliveries.
2. Filter by Scan ID, by status, or by endpoint when you have more than one.
3. Click a row to open it. You see each attempt with its HTTP status and time, and the exact payload that was sent.
4. To send it again, click Resend. To resend every failed delivery for an endpoint, click Resend N failed on its row.

​

Rotate the secret

1. On the endpoint’s row, click Rotate secret and confirm.
2. Copy the new secret from the Signing secret dialog, tick I’ve stored this secret. and click Done.
3. Deploy the new secret to your receiver alongside the old one. Until it is activated, deliveries are still signed with the old secret in X-Sentinel-Signature-V2, and with the new one in X-Sentinel-Signature-V2-Next.
4. Click Activate now, or wait: the new secret takes over 24 hours after you rotated.
5. Remove the old secret from your receiver.

​

What each result means

​

Events

​

Payload fields

​

Delivery statuses

​

Retries and pausing

​

Common questions

​

Can a delivery arrive twice?

​

Can I allowlist Sentinel’s IP addresses?

​

Do test-key checks send webhooks?

​

Does Sentinel read my endpoint’s response?

​

Who hears about a paused endpoint?

​

Related guides

• Quick start
• KYC API
• AML and monitoring API
• Results and credits
• A9 Notifications (in Sentinel’s in-app Help)