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:

dossier.invite.created: an invite has been created.
dossier.invite.expired: an invite has expired.
dossier.invite.undelivered: an invite cannot be delivered.
dossier.invite.viewed: the invite has been viewed by the invitee.
dossier.invitee.state.updated: the invitee state is updated. For example, to approved or declined.
dossier.prepared: the prepare step has been completed: fields are added to the dossier and invites should be sent.
dossier.state.updated: the state of the dossier is updated. For example, from pending to completed.
dossier.invitee.reassignRequest.state.updated: the state of the reassign request is updated. For example, from pending to approved.

By default the the dossier.state.updated, dossier.prepared and dossier.invite.undelivered 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://.

POST https://api.cm.com/sign/v1/clients/{kid}/webhooks

Replace {kid} with the client Key ID

Request headers

Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE

Request body

{
    "url": "https://example.com",
    "events": [
        "dossier.state.updated",
        "dossier.prepared",
        "dossier.invite.undelivered"
    ]
}

Custom headers

Custom headers can optionally be provided in the headers field:

{
    "url": "https://example.com",
    "headers": {
        "My-Custom-Header": "Example"
    }
}

Response

{
    "id": "77e79832-1708-4a49-9528-3536ba4057d7",
    "url": "https://example.com",
    "events": [
        "dossier.state.updated",
        "dossier.prepared"
    ],
    "headers": null,
    "updatedAt": "2022-01-01T00:00:00+00:00",
    "createdAt": "2022-01-01T00:00:00+00:00"
}

Retrieve status callback

A webhook URL can be configured for your Key ID so you get notified about status updates for dossiers.

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

Request headers

Content-Type: application/json

Request body

{
    "id": "b041a287-bc92-4469-801e-ae1a39c08f6e",
    "type": "dossier.state.updated",
    "dossier": {
        "id": "b659c273-954e-43cf-893a-0f74a7f87153",
        "state": "completed"
    },
    "created": "2022-01-01T00:00:00+00:00"
}

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 status code 5xx, the webhook will be retried several times with an exponentially increasing delay.