Transaction Monitoring Webhooks

Transaction Monitoring emits three webhook events that together cover the full transaction lifecycle. All ride on the standard Didit webhook infrastructure with HMAC-SHA256 signing - see the webhooks reference for destinations, signing, and testing.

Event catalog

Event	When it fires
`transaction.created`	A new transaction was created and initial evaluation completed. Also fires for inbound transactions minted by an after-deposit Travel Rule sunrise registration.
`transaction.status.updated`	The transaction’s status changed - from analyst review, remediation session resolution, wallet-ownership completion, or a Travel Rule outcome applying your `timeout_outcome`.
`travel_rule.status.updated`	A Travel Rule exchange transitioned, on both the outbound and any `INTERNAL`-rail inbound leg.

Entity-level events (user.status.updated, business.status.updated) can also fire as a consequence of transaction activity - see entity webhooks.

Sandbox applications do not emit transaction or travel-rule webhooks - test deliveries against a live application, or use API & Webhooks → Try Webhook in the console.

Envelope

Didit webhooks use a flat body: the event fields sit at the top level next to the envelope fields - there is no nested data object. Every delivery carries:

Field	Description
`webhook_type`	The event name, e.g. `transaction.created`.
`event_id`	Stable identifier for the event - the same `event_id` is reused on retries, so de-dupe on it.
`timestamp` / `created_at`	Unix epoch seconds when the delivery was dispatched.
`application_id`	The application the event belongs to.
`environment`	`live` or `sandbox`.

Payload shapes

`transaction.created` and `transaction.status.updated`

Both events share one payload - a compact summary plus the action_required block (or null):

{
  "webhook_type": "transaction.created",
  "event_id": "9c0c8b8a-1111-4222-9333-666666666666",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "9c7d2a30-...",
  "txn_id": "tx-0001",
  "status": "IN_REVIEW",
  "score": 65,
  "severity": "MEDIUM",
  "amount": "500.00",
  "currency": "EUR",
  "direction": "OUTBOUND",
  "action_required": null
}

The payload is deliberately thin: on receipt, fetch the full record with GET /v3/transactions/{transaction_id}/ - it returns the complete detail (parties, rule_runs, provider_results, travel_rule, cost_breakdown, decision_reason_code), including why the status changed.

`travel_rule.status.updated`

{
  "webhook_type": "travel_rule.status.updated",
  "event_id": "9c0c8b8a-1111-4222-9333-777777777777",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "travel_rule_status": "COMPLETED",
  "rail": "INTERNAL",
  "direction": "OUTBOUND"
}

Fires on every non-terminal transition; once a transfer reaches FINISHED, CANCELLED, or EXPIRED, no further travel-rule events are sent for it.

Example status journeys

Simple approval

transaction.created (APPROVED, score 0)

Review-then-approve

transaction.created (IN_REVIEW, score 65)
...analyst reviews...
transaction.status.updated (status: APPROVED)

Step-up verification

transaction.created (AWAITING_USER, action_required.type: verification_session)
...user completes the biometric re-check...
transaction.status.updated (status: APPROVED, action_required: null)

Travel Rule transfer

transaction.created (APPROVED)  +  travel_rule.status.updated (AWAITING_COUNTERPARTY, rail: EMAIL)
...counterparty accepts the pickup...
travel_rule.status.updated (COMPLETED)
...you broadcast on-chain and PATCH the hash...
travel_rule.status.updated (FINISHED)

Signature verification

Every delivery is HMAC-SHA256 signed with the destination’s shared secret and carries three signature headers plus a timestamp:

Header	Scheme
`X-Signature-V2`	HMAC over the canonical JSON (sorted keys, Unicode preserved) - recommended.
`X-Signature`	HMAC over the ASCII-escaped canonical JSON (legacy).
`X-Signature-Simple`	HMAC over `"{timestamp}:{session_id}:{status}:{webhook_type}"`.
`X-Timestamp`	Unix epoch seconds - reject deliveries older than 5 minutes.

import { createHmac, timingSafeEqual } from 'crypto';

function verify(rawBody: string, signatureV2: string, secret: string) {
  const canonical = JSON.stringify(
    Object.keys(JSON.parse(rawBody)).sort()
      .reduce((acc, k) => ({ ...acc, [k]: JSON.parse(rawBody)[k] }), {})
  );
  const expected = createHmac('sha256', secret).update(canonical).digest('hex');
  return timingSafeEqual(Buffer.from(signatureV2), Buffer.from(expected));
}

See the webhooks reference for the full verification code, including the timestamp freshness check.

Retries and delivery guarantees

On a 5xx, 404, timeout, or connection failure, Didit retries up to 2 times: roughly 1 minute after the initial failure, then roughly 4 more minutes after that.
Retried deliveries reuse the same event_id - de-dupe on it in your handler.
After the final failure, delivery for that event stops and your organization is notified; destinations are never silently disabled.
Return a 2xx fast (enqueue, then process) - slow ACKs risk timeouts and duplicate deliveries.

Idempotency

Process each webhook exactly once by storing event_id in your own dedupe store. Re-delivery of the same event is possible when your endpoint ACKs slowly or disconnects mid-request.

Subscribing

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "TM events",
    "url": "https://yourapp.com/webhooks/didit-tm",
    "subscribed_events": [
      "transaction.created",
      "transaction.status.updated",
      "travel_rule.status.updated"
    ]
  }'

Next steps

Webhooks reference

Destinations, signing, retries.

Statuses

Full state machine.

Integration guide

Handling webhooks in production.

Getting Started

Features

Reference

Console

Event catalog

Envelope

Payload shapes

`transaction.created` and `transaction.status.updated`

`travel_rule.status.updated`

Example status journeys

Simple approval

Review-then-approve

Step-up verification

Travel Rule transfer

Signature verification

Retries and delivery guarantees

Idempotency

Subscribing

Next steps

Webhooks reference

Statuses

Integration guide

​Event catalog

​Envelope

​Payload shapes

​transaction.created and transaction.status.updated

​travel_rule.status.updated

​Example status journeys

​Simple approval

​Review-then-approve

​Step-up verification

​Travel Rule transfer

​Signature verification

​Retries and delivery guarantees

​Idempotency

​Subscribing

​Next steps

Webhooks reference

Statuses

Integration guide

Event catalog

Envelope

Payload shapes

`transaction.created` and `transaction.status.updated`

`travel_rule.status.updated`

Example status journeys

Simple approval

Review-then-approve

Step-up verification

Travel Rule transfer

Signature verification

Retries and delivery guarantees

Idempotency

Subscribing

Next steps