Skip to main content

Events

A webhook can be added to subscribe to events that occur. When an event occurs, a trigger is sent to a predefined URL.

Event webhooks​

Supported event types:

TypeDescription
transaction.state.updatedThe transaction state has been updated.
task.state.updatedThe task state has been updated.

By default, the transaction.state.updated and task.state.updated events are sent.

Subscribe to event(s)​

Adding a webhook can be done by the using the webhook endpoint. It is mandatory to start the URL with https://.

Request
POST https://api.cm.com/id-scan/v1/webhooks
Request headers
Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE
Request body
{
    "url": "https://example.com",
    "events": [
        "transaction.state.updated",
        "task.state.updated"
    ]
}

Custom headers

Custom headers can optionally be provided in the headers field:

Request body
{
    "url": "https://example.com",
    "headers": {
        "My-Custom-Header": "Example"
    }
}
Response body
{
    "id": "77e79832-1708-4a49-9528-3536ba4057d7",
    "url": "https://example.com",
    "events": [
        "transaction.state.updated",
        "task.state.updated"
    ],
    "headers": null,
    "updated": "2026-01-01T00:00:00+00:00",
    "created": "2026-01-01T00:00:00+00:00"
}

Retrieve status callback​

A webhook URL can be configured so you get notified about status updates for transactions or tasks.

Webhooks can be configured via the API. Check the API reference for more details.

Request headers
Content-Type: application/json
transaction.state.updated
{
    "id": "b041a287-bc92-4469-801e-ae1a39c08f6e",
    "type": "transaction.state.updated",
    "created": "2026-01-01T00:00:00+00:00",
    "transaction": {
        "id": "b659c273-954e-43cf-893a-0f74a7f87153",
        "state": "completed",
        "resultId": "e6b7ce66-df56-4316-bb36-3d014ed84636"
    }
}

A task.state.updated event contains the transaction and the task that changed:

task.state.updated
{
    "id": "c36f5fc9-b412-4aeb-9cbd-bdb6cdca581f",
    "type": "task.state.updated",
    "created": "2026-01-01T00:00:00+00:00",
    "transaction": {
        "id": "b659c273-954e-43cf-893a-0f74a7f87153",
        "state": "pending"
    },
    "task": {
        "type": "document_scan",
        "state": "completed"
    }
}

Response

The status code should be in the 2xx range (between 200 and 300), the response body doesn't matter as it's ignored. In case of a 4xx status code, the webhook event is dropped and not retried. In case of a 5xx status code, a timeout or a connection error, the webhook event will be retried a few times with an increasing delay before it's dropped.