Alert webhooks

Alert webhooks send your team’s alerts to an HTTPS endpoint you own. Use them to feed an on-call tool, a ticket queue or your own operations dashboard. Alert webhooks are separate from verification webhooks. Verification webhooks send session, entity and transaction results to your application. Alert webhooks tell your team that something needs attention: a verification waiting for review, a failed payment, a service incident. They have their own payload, signing secret, signature and retry schedule.

Set up a destination

You configure alert webhooks in the Business Console, not through the API. Members who can manage organization settings can add, change and test destinations.

Add the destination

In Organization settings > Team notifications, add an Alert webhook destination with your endpoint’s URL. The URL must use https:// and resolve to a public address.

Store the signing secret

Didit shows the full signing secret, which starts with whsec_, only once. Store it now: afterwards the console shows only its last four characters.

Route alerts to it

Adding a destination does not send anything to it yet. Add the destination to the routing rules of the alerts you want it to receive.

Send a test

Click Send test to send an alert.test alert, and check that your endpoint accepts it.

An organization can have up to 25 destinations in Team notifications. Only live activity reaches a destination. Alerts about sandbox verifications, business verifications, transactions and AML hits are never sent to it.

Alert types

`webhook_type`	`severity`	When Didit sends it
`alert.verification.in_review`	`warning`	A verification was completed and flagged for manual review.
`alert.business_verification.in_review`	`warning`	A business verification needs manual review.
`alert.transaction.held`	`warning`	Your transaction monitoring rules flagged a transaction for review.
`alert.aml.monitoring_hit`	`warning`	Ongoing AML monitoring found a new hit.
`alert.billing.low_balance`	`warning`	Your organization’s balance dropped below the threshold you set.
`alert.billing.autorefill_failed`	`critical`	An automatic top-up of your balance failed because the card was declined.
`alert.billing.backup_card_charged`	`warning`	An automatic charge was declined on one card and paid with a backup card.
`alert.webhook.delivery_failing`	`warning`	Deliveries to one of your verification webhook endpoints are failing.
`alert.service.degraded`	`critical`	A service your organization uses is degraded or down.
`alert.service.recovered`	`info`	That service is back to normal.
`alert.test`	`info`	Someone clicked Send test on the destination.

Payload

Every alert is a POST with a JSON body. Didit sends the body as compact JSON with its keys sorted. This example is formatted for reading:

{
  "alert_id": "alt_9f2c4e1a7b3d5c80",
  "created_at": 1791884460,
  "data": {
    "event": "session_in_review",
    "label": "Session",
    "value": "#1042"
  },
  "organization": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Example Org"
  },
  "severity": "warning",
  "subtitle": "A KYC or KYB verification was completed and flagged for manual review.",
  "title": "Verification in review",
  "url": "https://business.didit.me/console/3fa85f64-5717-4562-b3fc-2c963f66afa6/9b2d1c4e-8f3a-4e6b-a1d2-5c7e9f0b3a14/verifications?session-id=1b4e28ba-2fa1-41d2-883f-0016d3cca427",
  "webhook_type": "alert.verification.in_review"
}

Field	Type	Description
`webhook_type`	string	`alert.` followed by the alert type. See Alert types.
`alert_id`	string	`alt_` followed by 16 hexadecimal characters. Every retry of an alert carries the same `alert_id`, so use it to ignore duplicates.
`created_at`	integer	Unix seconds when Didit created the alert. It stays the same on retries.
`severity`	string	`info`, `warning` or `critical`.
`organization`	object	Your organization’s `id` (UUID) and `name`.
`title`	string	Short English headline.
`subtitle`	string	English explanation. Can be empty.
`data`	object	What the alert is about. See below.
`url`	string	Link to the related page in the Didit console.

data always contains:

event: the event key, for example session_in_review.
label and value: what the alert is about, for example Session and #1042.

Some alert types add keys to data:

alert.billing.autorefill_failed adds paused, a boolean that is true when auto-refill is now paused until you update the card.
alert.service.degraded and alert.service.recovered add service, status, incident_id, service_name, state, affected, country_name, started_at, resolved_at, duration_minutes, title and body. status is degraded or down on alert.service.degraded, and recovered on alert.service.recovered. service uses the service keys of GET /v3/status/, and incident_id matches an incident id there.

Alerts never include end-user personal data or document data. They identify a session, transaction or other item by its number and link to it in the console. Ignore webhook_type values and data keys you do not recognize, so new ones do not break your endpoint.

Request headers

Header	Example	Meaning
`Content-Type`	`application/json`	The body is JSON.
`User-Agent`	`Didit-Alerts/1.0`	Identifies Didit’s alert sender.
`X-Timestamp`	`1791884462`	Unix seconds when Didit signed this attempt. New on every attempt.
`X-Signature-V2`	64 hexadecimal characters	HMAC-SHA256 signature of this attempt.

Verify the signature

X-Signature-V2 is the hex-encoded HMAC-SHA256 of the string <X-Timestamp>.<raw body>, keyed with your destination’s signing secret.

Use the full secret exactly as Didit showed it, including the whsec_ prefix.
Sign the raw request bytes as you received them. Parsing the JSON and serializing it again can change the bytes and break the check.
Compare the signatures in constant time.
Reject a request whose X-Timestamp is more than 5 minutes away from your clock. Didit signs every attempt, including each retry, with a fresh timestamp, so this window never rejects a genuine retry.
Answer a failed check with 400. A 401, 403, 404 or 410 response marks the destination for reconnection (see Retries).

Alert webhooks are not signed like verification webhooks. The header is also called X-Signature-V2, but the signed string is different, and alert webhooks send no X-Signature or X-Signature-Simple. Do not reuse your verification webhook verifier.

Node.js (Express)

const express = require("express");
const crypto = require("crypto");

const app = express();
// The full secret Didit showed when you added the destination, including "whsec_".
const ALERT_SECRET = process.env.DIDIT_ALERT_SECRET;
const TOLERANCE_SECONDS = 300;

// express.raw keeps the body as the exact bytes Didit sent.
app.post("/api/didit/alerts", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-Timestamp") || "";
  const signature = Buffer.from(req.get("X-Signature-V2") || "", "utf8");

  const now = Math.floor(Date.now() / 1000);
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) {
    return res.status(400).send("Stale or missing timestamp");
  }

  const expected = Buffer.from(
    crypto.createHmac("sha256", ALERT_SECRET).update(`${timestamp}.`).update(req.body).digest("hex"),
    "utf8",
  );
  if (signature.length !== expected.length || !crypto.timingSafeEqual(signature, expected)) {
    return res.status(400).send("Invalid signature");
  }

  const alert = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(204); // answer within 5 seconds, then process
  handleAlert(alert); // skip an alert_id you already handled
});

Python (Flask)

import hashlib
import hmac
import json
import os
import time

from flask import Flask, request

app = Flask(__name__)
# The full secret Didit showed when you added the destination, including "whsec_".
ALERT_SECRET = os.environ["DIDIT_ALERT_SECRET"].encode("utf-8")
TOLERANCE_SECONDS = 300


@app.post("/api/didit/alerts")
def didit_alert():
    raw_body = request.get_data()  # the exact bytes Didit sent
    timestamp = request.headers.get("X-Timestamp", "")
    signature = request.headers.get("X-Signature-V2", "")

    try:
        too_old = abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS
    except ValueError:
        too_old = True
    if too_old:
        return "Stale or missing timestamp", 400

    expected = hmac.new(ALERT_SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected.encode(), signature.encode()):
        return "Invalid signature", 400

    alert = json.loads(raw_body)
    handle_alert(alert)  # skip an alert_id you already handled; keep this fast
    return "", 204

Rotate the signing secret

You rotate the secret on the destination in Team notifications. Didit shows the new secret once and signs every later attempt with it, including retries of alerts created before the rotation. The old secret stops working at once. There is no overlap period, and no header carries a signature made with the previous secret. Deploy the new secret to your endpoint as soon as you rotate it.

Retries

Didit treats any 2xx response as delivered. Each attempt waits up to 5 seconds for your response and does not follow redirects. Didit retries an alert after a timeout, a connection failure, a 5xx response, or a 408, 425 or 429 response. It retries up to 5 times, over about 24 hours:

Retry	Delay after the previous attempt
1st	1 minute
2nd	5 minutes
3rd	30 minutes
4th	3 hours
5th	20 hours 24 minutes

Every other response is final, including 3xx and any other 4xx. A test sent with Send test gets a single attempt and is never retried. A 401, 403, 404 or 410 response also marks the destination for reconnection: the console shows it with a Reconnect status. So does a URL that resolves to a private or otherwise blocked address when Didit sends. Didit keeps sending new alerts to the destination, and it becomes active again after the next successful delivery or when you update its URL. Recent notifications in Team notifications lists each delivery with its result, and you can retry a failed delivery from there.

Verification webhooks: session, entity and transaction results for your application.
Service status: the public feed behind alert.service.degraded and alert.service.recovered.
Manual review: what to do with a verification in review.

Guides

Authentication

Model Context Protocol (MCP)

Web SDKs

Native SDKs

Integrations

Set up a destination

Alert types

Payload

Request headers

Verify the signature

Node.js (Express)

Python (Flask)

Rotate the signing secret

Retries

​Set up a destination

​Alert types

​Payload

​Request headers

​Verify the signature

​Node.js (Express)

​Python (Flask)

​Rotate the signing secret

​Retries

​Related

Set up a destination

Alert types

Payload

Request headers

Verify the signature

Node.js (Express)

Python (Flask)

Rotate the signing secret

Retries

Related