Skip to main content
Transaction Monitoring emits two top-level webhook events that together cover the full transaction lifecycle. Both use the standard Didit webhook envelope with HMAC-SHA256 signing.

​
Event catalog

EventWhen it fires
transaction.createdA new transaction was created and initial evaluation completed.
transaction.status.updatedThe transaction’s status changed — from asynchronous rule completion, analyst review, remediation session resolution, or provider callbacks.
Entity-level events (user.status.updated, business.status.updated) can also fire as a consequence of transaction activity — see entity webhooks.

​
Envelope

{
  "event": "transaction.created",
  "event_id": "evt_01H8X...",
  "application_id": "app_abc123",
  "timestamp": "2026-04-16T12:30:00Z",
  "data": { ... }
}

​
Payload shapes

​
transaction.created

Fires synchronously after every POST /v3/transactions/ call. 
{
  "event": "transaction.created",
  "data": {
    "transaction_id": "9c7d2a30-...",
    "txn_id": "tx-0001",
    "status": "APPROVED",
    "score": 0,
    "direction": "OUTBOUND",
    "amount": "500.00",
    "currency": "EUR",
    "amount_in_default_currency": "540.00",
    "default_currency_code": "USD",
    "applicant_vendor_data": "user-42",
    "counterparty_vendor_data": null,
    "rules_matched_count": 0,
    "created_at": "2026-04-16T12:30:00Z"
  }
}

​
transaction.status.updated

Fires on every status change after creation. 
{
  "event": "transaction.status.updated",
  "data": {
    "transaction_id": "9c7d2a30-...",
    "txn_id": "tx-0001",
    "previous_status": "IN_REVIEW",
    "status": "APPROVED",
    "score": 65,
    "changed_at": "2026-04-16T13:00:00Z",
    "reason": "analyst_cleared",
    "actor": "analyst@yourcorp.com"
  }
}
Possible reason values:
ReasonMeaning
rule_async_completedAn async rule (e.g. external AML provider) finished and updated the score.
analyst_approved / analyst_declined / analyst_clearedAnalyst action in the console.
remediation_completedUser completed the linked remediation session.
remediation_failedUser failed the linked remediation session.
provider_updateA downstream provider returned a new result that flipped status.
api_patchedStatus was patched via console/API.

​
Example status journeys

​
Simple approval

transaction.created (APPROVED, score 0)

​
Review-then-approve

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

​
Review-then-decline-with-SAR

transaction.created (IN_REVIEW, score 75)
...analyst investigates, opens case, escalates to PENDING_SAR...
transaction.status.updated (previous: IN_REVIEW, status: DECLINED)

​
User remediation

transaction.created (AWAITING_USER, score 80)
...user completes remediation session...
transaction.status.updated (previous: AWAITING_USER, status: APPROVED)

​
Signature verification

Every webhook is HMAC-SHA256 signed with the destination’s shared secret, sent in the X-Didit-Signature header. 
import { createHmac, timingSafeEqual } from 'crypto';

function verify(rawBody: string, signature: string, secret: string) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
See webhooks reference for the full signing protocol.

​
Retries and delivery guarantees

  • Non-2xx responses retry with exponential backoff (1s → 2s → 4s → … up to 5 retries).
  • Total delivery window ~24 hours.
  • Every delivery carries a unique X-Didit-Delivery header but the same event_id — de-dupe on your side.
  • Repeated destination failures auto-disable the destination with an operator alert.

​
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"
    ]
  }'

​
Next steps

Webhooks reference

Destinations, signing, retries.

Statuses

Full state machine.

Integration guide

Handling webhooks in production.