Platform

Webhooks

Copy page

Both Document Verification and AML Screening emit webhook events as processing progresses. Instead of polling, configure a webhook destination and your endpoint will receive a POST request the moment an event fires.

Setting Up Webhooks

In the Developer Console of your Dossiers Dashboard:

1. Navigate to the Webhooks section
2. Click Create Destination
3. Enter a publicly reachable HTTPS URL that accepts POST requests
4. Select the events you want to subscribe to
5. Save — a signing secret is generated automatically

Store the signing secret securely. You'll use it to verify that incoming payloads genuinely come from Dossiers.

Payload Format

Every webhook delivery is a POST request with a JSON body:

Code
{
  "id": "evt_01HZ...",
  "type": "documentVerification.instance.updated",
  "organizationId": "org_...",
  "createdAt": "2026-03-05T11:35:06.000Z",
  "data": {
    "processorId": "SRI_LANKA_ID",
    "documentProcessorInstanceId": "65f3c1a2b4e5f60012345678",
    "status": "completed",
    "statusLabel": "Post-validation complete",
    "stageProgress": [
      { "stageId": "crop_and_detect_faces", "label": "Scanning", "status": "success" },
      { "stageId": "pre_validate_and_extract", "label": "Extracting", "status": "success" },
      { "stageId": "post_validation", "label": "Post-validation", "status": "success" }
    ],
    "error": null
  }
}

Field	Description
id	Unique event ID
type	Event type string (e.g. documentVerification.instance.updated)
organizationId	Your organization ID
createdAt	ISO 8601 timestamp of when the event was created
data	Event-specific payload (varies by event type)

Verifying Signatures

Every delivery includes an X-Webhook-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your destination secret.

Always verify the signature before trusting the payload. Use the raw (unparsed) request body for the HMAC computation — parsing JSON first will break the digest.

Node.js

Code
const crypto = require('crypto');

function isValidSignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your Express handler:
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!isValidSignature(req.body, WEBHOOK_SECRET, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Process the event...

  res.status(200).send('OK');
});

Python

Code
import hmac
import hashlib

def is_valid_signature(raw_body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Delivery Headers

Each delivery includes these headers:

Header	Description
X-Webhook-Signature	HMAC-SHA256 hex digest of the payload
X-Webhook-Event-Type	Event type string (e.g. documentVerification.instance.updated)
X-Webhook-Event-Id	Unique event ID (same as the id field in the payload)
X-Webhook-Retry-Count	Number of previous failed delivery attempts (0 on first attempt)

Delivery and Retries

• Your endpoint must return a 2xx response within 10 seconds
• Failed deliveries (non-2xx or timeout) are retried automatically with exponential back-off
• Delivery history and per-event logs are available in the Developer Console under Webhook Logs

Event Reference

Document Verification Events

Event Type	Description
documentVerification.instance.created	A new processing instance has been created
documentVerification.instance.updated	The instance status or result has changed (fires after each pipeline stage completes, and again on final completion or failure)
documentVerification.instance.deleted	An instance was deleted

Instance Statuses

Status	Meaning
pending	Queued, processing has not started
running	Pipeline is actively executing
completed	All stages finished successfully
failed	A document-level issue was detected (wrong document type, unreadable, validation failure)
error	An internal infrastructure issue prevented processing (timeout, service crash)

instance.updated Payload

Every updated event includes a stageProgress array that tracks each pipeline stage. This lets you render a progress stepper or determine exactly where processing is at — or where it failed.

Code
{
  "id": "evt_01HZ...",
  "type": "documentVerification.instance.updated",
  "organizationId": "org_...",
  "createdAt": "2026-03-05T11:35:12.000Z",
  "data": {
    "processorId": "SRI_LANKA_ID",
    "documentProcessorInstanceId": "65f3c1a2b4e5f60012345678",
    "status": "running",
    "statusLabel": "Extracting data",
    "stageProgress": [
      { "stageId": "crop_and_detect_faces", "label": "Scanning", "status": "success" },
      { "stageId": "pre_validate_and_extract", "label": "Extracting", "status": "running" },
      { "stageId": "visual_integrity_check", "label": "Integrity check", "status": "running" },
      { "stageId": "post_validation", "label": "Post-validation", "status": "pending" },
      { "stageId": "voter_registry", "label": "Voter registry", "status": "pending" }
    ],
    "error": null
  }
}

Field	Description
status	Instance-level status (pending, running, completed, failed, error)
statusLabel	Short human-readable label describing the current activity or failure (e.g. "Extracting data", "Extraction failed")
stageProgress	Array of all pipeline stages with their current status (pending, running, success, failed)
error	Error message when status is failed or error, otherwise null

On failure, the stageProgress array shows exactly which stage failed:

Code
{
  "data": {
    "status": "failed",
    "statusLabel": "Extraction failed",
    "stageProgress": [
      { "stageId": "crop_and_detect_faces", "label": "Scanning", "status": "success" },
      { "stageId": "pre_validate_and_extract", "label": "Extracting", "status": "failed" },
      { "stageId": "visual_integrity_check", "label": "Integrity check", "status": "success" },
      { "stageId": "post_validation", "label": "Post-validation", "status": "pending" },
      { "stageId": "voter_registry", "label": "Voter registry", "status": "pending" }
    ],
    "error": "Document does not match any supported template type"
  }
}

instance.created Payload

Code
{
  "data": {
    "processorId": "SRI_LANKA_ID",
    "documentProcessorInstanceId": "65f3c1a2b4e5f60012345678"
  }
}

instance.deleted Payload

Code
{
  "data": {
    "deletedDocumentProcessorInstanceId": "65f3c1a2b4e5f60012345678"
  }
}

AML Screening Events

Event Type	Description
amlScreening.screeningRequest.created	New screening request submitted
amlScreening.screeningRequest.completed	Screening processing finished
amlScreening.screeningAlert.triggered	New high-risk match found
amlScreening.screeningAlert.statusChanged	Alert status updated (e.g. confirmed, dismissed)
amlScreening.screeningAlert.commentAdded	Comment added to an alert
amlScreening.screeningAlert.commentDeleted	Comment removed from an alert
amlScreening.screeningAlert.deleted	Alert deleted

System Events

These events fire regardless of which products are enabled:

Event Type	Description
system.testEvent	Test event for verifying webhook connectivity
system.product.accessGranted	A product has been enabled for your organization
system.product.accessRevoked	A product has been disabled for your organization
system.apiKey.created	A new API key was created
system.apiKey.invalidated	An API key was revoked
system.usage.limitReached	Your organization has hit its credit usage limit
system.usage.limitWarning	Your organization is approaching its credit usage limit

Managing Destinations

From the Developer Console you can:

• Update a destination's URL or subscribed events
• Enable/disable a destination without deleting it
• Regenerate the signing secret (rotates the secret; old deliveries will still use the previous secret)
• Send a test event to verify connectivity
• Delete a destination entirely

Best Practices

• Always verify signatures — Never trust a payload without checking the HMAC signature
• Respond quickly — Return a 2xx within 10 seconds. If you need to do heavy processing, acknowledge the webhook and handle the work asynchronously
• Handle duplicates — Use the event id to deduplicate, as retries may deliver the same event more than once
• Use HTTPS — Webhook destinations must use HTTPS to protect payloads in transit
• Monitor delivery logs — Check the Developer Console for failed deliveries and investigate any persistent errors