Webhook Payloads

Reference documentation for all webhook event payloads. Each payload captures the verification state at the time the event fired.

See the Webhooks Guide for setup instructions, delivery management, and signature verification.

Event Types

Colleckt fires four verification lifecycle events. Each event delivers a JSON payload with the same top-level structure but different data depending on the verification state.

Verification Started

Fires when a new verification is created and the applicant has not yet submitted their information.

Code: verification.started

json

{
  "event": "verification.started",
  "data": {
    "id": "ver_xxxxx",
    "url": "https://{workspace}.colleckt.io/spa/v3/.../process",
    "qr_code": "https://{workspace}.colleckt.io/qr/...",
    "flow": "usps-1583",
    "expected_data": {
      "person": {
        "first_name": "Homer",
        "last_name": "Simpson",
        "date_of_birth": "1988-05-06"
      },
      "address": {
        "street": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "Tennessee",
        "postal_code": "92026",
        "country": "USA"
      },
      "documents": {
        "photo_id": {
          "type": "Passport",
          "number": "AB123456",
          "country": "USA"
        },
        "proof_of_address": {
          "type": "Driver License",
          "number": "",
          "country": "USA"
        }
      }
    },
    "extracted_data": null,
    "vendor_reference": "REF-001",
    "vendor_state": "TN",
    "documents": [],
    "comments": [],
    "status_label": "Started",
    "created_at": "2026-06-14T02:14:13.000000Z",
    "updated_at": "2026-06-14T02:14:13.000000Z"
  }
}

Key characteristics:

documents is empty — the applicant has not uploaded anything yet
extracted_data is null — no OCR processing has occurred
comments is empty — no activity yet

Verification Submitted

Fires when the applicant submits their information for processing. Documents have been uploaded but not yet processed.

Code: verification.submitted

json

{
  "event": "verification.submitted",
  "data": {
    "id": "ver_xxxxx",
    "url": "https://{workspace}.colleckt.io/spa/v3/.../process",
    "qr_code": "https://{workspace}.colleckt.io/qr/...",
    "flow": "usps-1583",
    "expected_data": {
      "person": {
        "first_name": "Homer",
        "last_name": "Simpson",
        "date_of_birth": "1988-05-06"
      },
      "address": {
        "street": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "Tennessee",
        "postal_code": "92026",
        "country": "USA"
      },
      "documents": {
        "photo_id": {
          "type": "Passport",
          "number": "AB123456",
          "country": "USA"
        },
        "proof_of_address": {
          "type": "Driver License",
          "number": "",
          "country": "USA"
        }
      }
    },
    "extracted_data": null,
    "vendor_reference": "REF-001",
    "vendor_state": "TN",
    "documents": [
      {
        "id": "doc_xxxxx",
        "url_front": "https://{workspace}.colleckt.io/spa/v3/.../process",
        "url_back": "",
        "status_label": "Uploaded",
        "verification_id": "ver_xxxxx",
        "document_type": {
          "id": 1,
          "name": "Passport",
          "type_label": "Photo ID"
        },
        "country": {
          "name": "United States of America",
          "iso2": "US",
          "iso3": "USA"
        },
        "created_at": "2026-06-14T02:14:50.000000Z",
        "updated_at": "2026-06-14T02:14:50.000000Z",
        "extracted_data": null,
        "decisions": [],
        "rules": null
      },
      {
        "id": "doc_xxxxx",
        "url_front": "https://{workspace}.colleckt.io/spa/v3/.../process",
        "url_back": "",
        "status_label": "Uploaded",
        "verification_id": "ver_xxxxx",
        "document_type": {
          "id": 10,
          "name": "Driver License",
          "type_label": "Proof of Address"
        },
        "country": {
          "name": "United States of America",
          "iso2": "US",
          "iso3": "USA"
        },
        "created_at": "2026-06-14T02:15:00.000000Z",
        "updated_at": "2026-06-14T02:15:00.000000Z",
        "extracted_data": null,
        "decisions": [],
        "rules": null
      }
    ],
    "comments": [],
    "status_label": "Submitted",
    "created_at": "2026-06-14T02:14:13.000000Z",
    "updated_at": "2026-06-14T02:15:00.000000Z"
  }
}

Key characteristics:

documents now contains uploaded documents with status_label: "Uploaded" and full structure (document_type, country, etc.)
extracted_data is still null — OCR has not completed
decisions is empty and rules is null for all documents — no processing yet
updated_at reflects the submission time

Verification Finished

Fires when a verification reaches a final decision (approved or rejected).

Double Check

Webhooks are not sent when a verification reaches Double Check status. The finished event fires only after a human reviewer approves or rejects the verification.

Code: verification.finished

json

{
  "event": "verification.finished",
  "data": {
    "id": "ver_xxxxx",
    "url": "https://{workspace}.colleckt.io/spa/v3/.../process",
    "qr_code": "https://{workspace}.colleckt.io/qr/...",
    "flow": "usps-1583",
    "expected_data": {
      "person": {
        "first_name": "Homer",
        "last_name": "Simpson",
        "date_of_birth": "1988-05-06"
      },
      "address": {
        "street": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "Tennessee",
        "postal_code": "92026",
        "country": "USA"
      },
      "documents": {
        "photo_id": {
          "type": "Passport",
          "number": "AB123456",
          "country": "USA"
        },
        "proof_of_address": {
          "type": "Driver License",
          "number": "",
          "country": "USA"
        }
      }
    },
    "extracted_data": {
      "photo_id": {
        "person": {
          "surname": "Simpson",
          "full_name": "Simpson Homer",
          "given_names": "Homer",
          "date_of_birth": "1988-05-06"
        },
        "address": {
          "zip": "92026",
          "city": "Springfield",
          "full": "742 Evergreen Terrace, Springfield, Tennessee 92026",
          "state": "Tennessee",
          "street": "742 Evergreen Terrace",
          "country": "USA"
        },
        "document": {
          "type": "Passport",
          "number": "AB123456",
          "has_selfie": "1",
          "identified": "United States of America - Passport",
          "country_code": "USA",
          "country_name": "United States of America",
          "issuing_entity": "Government",
          "expiration_date": "2030-06-14",
          "selfie_comparison": "99"
        }
      },
      "proof_of_address": {
        "person": {
          "surname": "Simpson",
          "full_name": "Simpson Homer",
          "given_names": "Homer",
          "date_of_birth": "1988-05-06"
        },
        "address": {
          "zip": "92026",
          "city": "Springfield",
          "full": "742 Evergreen Terrace, Springfield, Tennessee 92026",
          "state": "Tennessee",
          "street": "742 Evergreen Terrace",
          "country": "USA"
        },
        "document": {
          "type": "Driver License",
          "number": "",
          "has_selfie": "0",
          "identified": "United States of America - Driver License",
          "country_code": "USA",
          "country_name": "United States of America",
          "issuing_entity": "Government",
          "expiration_date": "2028-07-23",
          "selfie_comparison": "0"
        }
      }
    },
    "vendor_reference": "REF-001",
    "vendor_state": "TN",
    "documents": [
      {
        "id": "doc_xxxxx",
        "url_front": "https://{workspace}.colleckt.io/spa/v3/.../process",
        "url_back": "",
        "status_label": "Approved",
        "verification_id": "ver_xxxxx",
        "document_type": {
          "id": 1,
          "name": "Passport",
          "type_label": "Photo ID"
        },
        "country": {
          "name": "United States of America",
          "iso2": "US",
          "iso3": "USA"
        },
        "created_at": "2026-06-14T02:14:50.000000Z",
        "updated_at": "2026-06-14T02:16:40.000000Z",
        "extracted_data": {
          "person": {
            "surname": "Simpson",
            "full_name": "Simpson Homer",
            "given_names": "Homer",
            "date_of_birth": "1988-05-06"
          },
          "address": {
            "zip": "92026",
            "city": "Springfield",
            "full": "742 Evergreen Terrace, Springfield, Tennessee 92026",
            "state": "Tennessee",
            "street": "742 Evergreen Terrace",
            "country": "USA"
          },
          "document": {
            "type": "Passport",
            "number": "AB123456",
            "has_selfie": "1",
            "identified": "United States of America - Passport",
            "country_code": "USA",
            "country_name": "United States of America",
            "issuing_entity": "Government",
            "expiration_date": "2030-06-14",
            "selfie_comparison": "99"
          }
        },
        "decisions": [
          {
            "id": "dec_xxxxx",
            "status_label": "Approved",
            "validation_workflow": "Automatic",
            "created_at": "2026-06-14T02:16:40.000000Z",
            "updated_at": "2026-06-14T02:16:40.000000Z"
          }
        ],
        "rules": {
          "id": "rule_xxxxx",
          "approved_rules": {
            "RulePH001": { "expected": "Homer Simpson", "extracted": "Homer Simpson" },
            "RulePH002": { "expected": "USA", "extracted": "USA" },
            "RulePH003": { "expected": "Passport", "extracted": "Passport" },
            "RulePH004": { "expected": "SIMPSON HOMER", "extracted": "Simpson Homer" },
            "RulePH005": { "expected": "AB123456", "extracted": "AB123456" },
            "RulePH006": { "expected": "1988-05-06", "extracted": "1988-05-06" },
            "RulePH007": { "expected": "Same document sides", "extracted": "Same document sides" }
          },
          "failed_rules": {},
          "suggestions": ["The document you uploaded is correct."]
        }
      },
      {
        "id": "doc_xxxxx",
        "url_front": "https://{workspace}.colleckt.io/spa/v3/.../process",
        "url_back": "https://{workspace}.colleckt.io/spa/v3/.../process",
        "status_label": "Approved",
        "verification_id": "ver_xxxxx",
        "document_type": {
          "id": 10,
          "name": "Driver License",
          "type_label": "Proof of Address"
        },
        "country": {
          "name": "United States of America",
          "iso2": "US",
          "iso3": "USA"
        },
        "created_at": "2026-06-14T02:15:00.000000Z",
        "updated_at": "2026-06-14T02:16:42.000000Z",
        "extracted_data": {
          "person": {
            "surname": "Simpson",
            "full_name": "Simpson Homer",
            "given_names": "Homer",
            "date_of_birth": "1988-05-06"
          },
          "address": {
            "zip": "92026",
            "city": "Springfield",
            "full": "742 Evergreen Terrace, Springfield, Tennessee 92026",
            "state": "Tennessee",
            "street": "742 Evergreen Terrace",
            "country": "USA"
          },
          "document": {
            "type": "Driver License",
            "number": "",
            "has_selfie": "0",
            "identified": "United States of America - Driver License",
            "country_code": "USA",
            "country_name": "United States of America",
            "issuing_entity": "Government",
            "expiration_date": "2028-07-23",
            "selfie_comparison": "0"
          }
        },
        "decisions": [
          {
            "id": "dec_xxxxx",
            "status_label": "Approved",
            "validation_workflow": "Automatic",
            "created_at": "2026-06-14T02:16:42.000000Z",
            "updated_at": "2026-06-14T02:16:42.000000Z"
          }
        ],
        "rules": {
          "id": "rule_xxxxx",
          "approved_rules": {
            "RuleAD001": { "expected": "Homer Simpson", "extracted": "Homer Simpson" },
            "RuleAD002": { "expected": "USA", "extracted": "USA" },
            "RuleAD003": { "expected": "Driver License", "extracted": "Driver License" },
            "RuleAD004": { "expected": "742 Evergreen Terrace", "extracted": "742 Evergreen Terrace" },
            "RuleAD005": { "expected": "742 Evergreen Terrace, Springfield, 92026, USA", "extracted": "742 Evergreen Terrace, Springfield, 92026, USA" },
            "RuleAD006": { "expected": "SIMPSON HOMER", "extracted": "Simpson Homer" }
          },
          "failed_rules": {},
          "suggestions": ["The document you uploaded is correct."]
        }
      }
    ],
    "comments": [],
    "status_label": "Approved",
    "created_at": "2026-06-14T02:14:13.000000Z",
    "updated_at": "2026-06-14T02:16:42.000000Z"
  }
}

Key characteristics:

extracted_data is a populated object keyed by document category (photo_id, proof_of_address)
Document objects include full extracted_data, decisions, and rules
Document statuses reflect final decisions (Approved, Rejected)
status_label reflects the outcome (e.g., "Approved", "Rejected")

Verification Canceled

Fires when a verification is canceled before reaching a final decision.

Code: verification.canceled

json

{
  "event": "verification.canceled",
  "data": {
    "id": "ver_xxxxx",
    "url": "https://{workspace}.colleckt.io/spa/v3/.../process",
    "qr_code": "https://{workspace}.colleckt.io/qr/...",
    "flow": "usps-1583",
    "expected_data": {
      "person": {
        "first_name": "Homer",
        "last_name": "Simpson",
        "date_of_birth": "1988-05-06"
      },
      "address": {
        "street": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "Tennessee",
        "postal_code": "92026",
        "country": "USA"
      },
      "documents": {
        "photo_id": {
          "type": "Passport",
          "number": "AB123456",
          "country": "USA"
        },
        "proof_of_address": {
          "type": "Driver License",
          "number": "",
          "country": "USA"
        }
      }
    },
    "extracted_data": null,
    "vendor_reference": "REF-001",
    "vendor_state": "TN",
    "documents": [],
    "comments": [
      {
        "content": "Caller requested cancellation.",
        "status": "Canceled",
        "created_at": "2026-06-14T03:00:00.000000Z"
      }
    ],
    "status_label": "Canceled",
    "created_at": "2026-06-14T02:14:13.000000Z",
    "updated_at": "2026-06-14T03:00:00.000000Z"
  }
}

Common Payload Fields

Every webhook payload follows this structure:

json

{
  "event": "<event_code>",
  "data": { /* verification data */ }
}

Top-level fields

All payloads follow the same top-level structure:

Field	Type	Description
`event`	string	The event code identifying what happened (e.g., `verification.finished`)
`data`	object	The verification snapshot at the time of the event

Data object fields

Field	Type	Nullable	Description
`id`	`string`	No	Unique verification ID
`url`	`string`	No	URL to the end-user verification widget
`qr_code`	`string`	No	QR code image URL for mobile access
`flow`	`string`	No	Flow slug (e.g., `usps-1583`, `identity`)
`expected_data`	`object`	No	Expected person, address, and document details. See Expected Data
`extracted_data`	`object`	Yes	OCR-extracted data keyed by document category (`photo_id`, `proof_of_address`). `null` before processing
`vendor_reference`	`string`	Yes	Your reference ID for the verification
`vendor_state`	`string`	Yes	Vendor state information
`documents`	`array`	No	Uploaded documents. See Verification Document
`comments`	`array`	No	Non-private comments (up to 3 most recent). See Comment
`status_label`	`string`	No	Human-readable status (e.g., `"Started"`, `"Submitted"`, `"Approved"`, `"Rejected"`, `"Canceled"`)
`created_at`	`string` (ISO 8601)	No	ISO 8601 timestamp of creation
`updated_at`	`string` (ISO 8601)	No	ISO 8601 timestamp of last update

Signature Header

Every webhook request includes a Signature header:

text

Signature: 6f8603bad35dd38facbb351d53c5d666ed36a01b6da270d998f883f527932b33

The value is the lowercase hexadecimal HMAC-SHA256 digest of the raw request body, computed using your webhook's unique 64-character signing secret.

text

HMAC-SHA256(raw_request_body, signing_secret) → hex

TIP

Manual resends from the webhook logs are sent without a Signature header. See the Webhooks Guide for details.

See the Webhooks Guide → Verifying Signatures for verification steps, code examples in multiple languages, and a test vector.

Webhook Payloads ​

Event Types ​

Verification Started ​

Verification Submitted ​

Verification Finished ​

Verification Canceled ​

Common Payload Fields ​

Top-level fields ​

Data object fields ​

Signature Header ​

Webhook Payloads

Event Types

Verification Started

Verification Submitted

Verification Finished

Verification Canceled

Common Payload Fields

Top-level fields

Data object fields

Signature Header