Webhook Payloads

Reference documentation for all webhook event payloads.

Event Types

Verification Started

Fired when a new verification is created.

Code: verification.started

{
  "type": "verification.started",
  "data": {
    "verification_id": "ver_xxxxx",
    "vendor_reference": "REF-001",
    "timestamp": "2026-06-10T20:50:15.000000Z"
  }
}

Verification Submitted

Fired when a verification is submitted for processing.

Code: verification.submitted

{
  "type": "verification.submitted",
  "data": {
    "verification_id": "ver_xxxxx",
    "vendor_reference": "REF-001",
    "timestamp": "2026-06-11T07:36:11.000000Z"
  }
}

Verification Finished

Fired when a verification reaches a final decision (approved, rejected, or double-check).

Code: verification.finished

{
  "type": "verification.finished",
  "data": {
    "verification_id": "ver_xxxxx",
    "status": "approved",
    "vendor_reference": "REF-001",
    "timestamp": "2026-06-11T07:36:42.000000Z"
  }
}

Verification Canceled

Fired when a verification is canceled.

Code: verification.canceled

{
  "type": "verification.canceled",
  "data": {
    "verification_id": "ver_xxxxx",
    "vendor_reference": "REF-001",
    "timestamp": "2026-06-11T08:00:00.000000Z"
  }
}

Document Uploaded

Fired when a document image is uploaded.

Code: document.uploaded

{
  "type": "document.uploaded",
  "data": {
    "document_id": "doc_xxxxx",
    "verification_id": "ver_xxxxx",
    "document_type": "PHOTO_ID",
    "timestamp": "2026-06-11T07:05:01.000000Z"
  }
}

Document Canceled

Fired when a document is canceled.

Code: document.canceled

{
  "type": "document.canceled",
  "data": {
    "document_id": "doc_xxxxx",
    "verification_id": "ver_xxxxx",
    "document_type": "PHOTO_ID",
    "timestamp": "2026-06-11T08:15:00.000000Z"
  }
}

Decision Made

Fired when a decision is made on a document (approve, reject, or double-check).

Code: decision.made

{
  "type": "decision.made",
  "data": {
    "decision_id": "dec_xxxxx",
    "document_id": "doc_xxxxx",
    "verification_id": "ver_xxxxx",
    "status": "approved",
    "timestamp": "2026-06-11T07:36:42.000000Z"
  }
}

Decision Canceled

Fired when a decision is canceled.

Code: decision.canceled

{
  "type": "decision.canceled",
  "data": {
    "decision_id": "dec_xxxxx",
    "document_id": "doc_xxxxx",
    "verification_id": "ver_xxxxx",
    "timestamp": "2026-06-11T08:30:00.000000Z"
  }
}

Payload Structure

Every webhook payload follows this structure:

Field	Type	Description
type	string	The event code (e.g., verification.finished)
data	object	Event-specific data

The data object varies by event type but consistently includes:

• verification_id — The verification involved
• timestamp — When the event occurred

Event-specific fields are included as appropriate (e.g., status for finished events, document_id for document events).

Verification

To verify that a webhook payload came from Colleckt:

1. Get the raw request body as a string
2. Get the Signature header value
3. Compute HMAC-SHA256 of the raw body using your webhook's signing secret
4. Base64-encode the HMAC output
5. Compare with the Signature header using a constant-time comparison

const crypto = require('crypto');

function verifySignature(payloadBody, signatureHeader, signingSecret) {
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(payloadBody)
    .digest('base64');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

function verifySignature(string $payloadBody, string $signatureHeader, string $signingSecret): bool {
    $expected = hash_hmac('sha256', $payloadBody, $signingSecret, true);
    return hash_equals(base64_decode($signatureHeader), $expected);
}