Webhook Notifications

All operations performed on the API are notified to the client via a webhook. The webhook URL can be configured by the client. Notifications are sent in JSON format and include two parameters:

operationType: Indicates the type of operation. Possible values: SIGNATURE_REQUESTS, DOCUMENTS, REPORTS, SIGNATURE_NOTIFICATIONS, VALIDATOR_NOTIFICATIONS, OBSERVER_NOTIFICATIONS, LEGAL_ENTITY_SIGNED.
data: Contains the details of the operation. The content of this field depends on the specific event.

Every webhook HTTP request also carries a tenant header identifying the tenant the event belongs to, in addition to the Authorization header described below.

Signature Request Webhook

For signature request operations, the JSON payload is structured as follows:

{
  "operationType": "SIGNATURE_REQUESTS",
  "data": {
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "status": "ACTIVE"
  }
}

Statuses can be: ACTIVE, DRAFT, CANCELLED, PARTIALLY_SIGNED, FULLY_SIGNED, COMPLETED, COMPLETED_MANUAL, COMPLETED_EXPIRED, REJECTED, ERROR, CANCELLED_EXPIRED.

When status is ERROR, the payload may also include operationType and errors:

{
  "operationType": "SIGNATURE_REQUESTS",
  "data": {
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "status": "ERROR",
    "operationType": "BULK_EDIT_OPERATION",
    "errors": [
      "Validation error in bulk edit"
    ]
  }
}

Bulk Delete Signature Requests Webhook

When a bulk delete signature requests process finishes, its result is notified with operationType set to SIGNATURE_REQUESTS as well, using a payload shape specific to the bulk process instead of a single signature request status:

{
  "operationType": "SIGNATURE_REQUESTS",
  "data": {
    "bulkDeleteProcessId": "0e9ee9f6-25d1-4dbd-8f27-e582d5b6f4a2",
    "status": "COMPLETED",
    "totalRequests": 2,
    "completedCount": 2,
    "errorCount": 0,
    "completedIds": [
      "e694c179-e503-4101-992e-329700c37adc",
      "55fc5ab7-2345-41fd-8688-6d04acf2b5bc"
    ],
    "erroredIds": []
  }
}

This bulk delete notification is always sent to the webhook URLs configured at client level; it does not use the webhookUris of any individual signature request (they no longer exist once deleted).

Document Webhook

For document operations, a similar JSON payload is used with operationType set to DOCUMENTS and data containing the specific details of the document-related event. The JSON payload is structured as follows

{
  "operationType": "DOCUMENTS",
  "data": {
    "documentId": "57081c08-08e7-4d7e-b10a-8a98d7b1b3bd",
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "status": "READY_TO_SIGN"
  }
}

Statuses can be: PENDING, READY_TO_SIGN, PARTIALLY_SIGNED, REJECTED, ERROR. Note that the SIGNED status does not trigger a document webhook.

When status is ERROR, the payload may also include operationType and errors:

{
  "operationType": "DOCUMENTS",
  "data": {
    "documentId": "57081c08-08e7-4d7e-b10a-8a98d7b1b3bd",
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "status": "ERROR",
    "operationType": "BULK_ADD_OPERATION",
    "errors": [
      "Document participant validation error"
    ]
  }
}

Signature Notification Webhook

For changes in a signatory's notification (the message sent to a signatory to sign a document), the JSON payload is structured as follows:

{
  "operationType": "SIGNATURE_NOTIFICATIONS",
  "data": {
    "signatoryId": "950fac7e-5284-42ad-8044-3f4632678324",
    "documentId": "57081c08-08e7-4d7e-b10a-8a98d7b1b3bd",
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "processName": "Signature Request 1",
    "type": "ADVANCED",
    "provider": "NOTICEMAN_AND_WHATSAPP",
    "dueDate": "2024-01-31T23:59:59Z",
    "createdBy": "creator@example.com",
    "signatureStatus": "READY_TO_SIGN",
    "email": "signatory@example.com",
    "phone": "123456789",
    "name": "Signatory Name",
    "surnames": "Signatory Surnames",
    "sequence": 1,
    "uniqueValidator": false,
    "registeredAt": "2023-10-23T10:34:59.483Z",
    "rejectionReason": null,
    "notification": {
      "id": "b2b16f42-8e65-4c6f-8253-ad6ded8ae111",
      "notificationId": "notif-123456",
      "status": "PENDING",
      "createdAt": "2023-10-23T10:34:59.483Z",
      "updatedAt": "2023-10-23T10:34:59.483Z",
      "landingUrl": "https://noticeman.example.com/landing/notif-123456"
    }
  }
}

notification.status can be: PENDING, REVIEWED, ANSWERED, CANCELLED, INFORMED, or BOUNCED when the provider reports that the message could not be delivered (see Signature Notification operations).

Validator Notification Webhook

For changes in a validator's notification, the JSON payload is structured as follows:

{
  "operationType": "VALIDATOR_NOTIFICATIONS",
  "data": {
    "validatorId": "d3c16f42-8e65-4c6f-8253-ad6ded8ae222",
    "documentId": "57081c08-08e7-4d7e-b10a-8a98d7b1b3bd",
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "processName": "Signature Request 1",
    "type": "ADVANCED",
    "provider": "NOTICEMAN",
    "dueDate": "2024-01-31T23:59:59Z",
    "createdBy": "creator@example.com",
    "validatorStatus": "PENDING",
    "email": "validator@example.com",
    "phone": "123456789",
    "name": "Validator Name",
    "surnames": "Validator Surnames",
    "registeredAt": "2023-10-23T10:34:59.483Z",
    "rejectionReason": null,
    "notification": {
      "id": "e4d16f42-8e65-4c6f-8253-ad6ded8ae333",
      "notificationId": "notif-789012",
      "status": "PENDING",
      "createdAt": "2023-10-23T10:34:59.483Z",
      "updatedAt": "2023-10-23T10:34:59.483Z"
    }
  }
}

notification.status can also be BOUNCED when the message could not be delivered.

Observer Notification Webhook

For changes in an observer's notification, the JSON payload is structured as follows:

{
  "operationType": "OBSERVER_NOTIFICATIONS",
  "data": {
    "observerId": "f5e16f42-8e65-4c6f-8253-ad6ded8ae444",
    "documentId": "57081c08-08e7-4d7e-b10a-8a98d7b1b3bd",
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "processName": "Signature Request 1",
    "type": "ADVANCED",
    "provider": "NOTICEMAN",
    "dueDate": "2024-01-31T23:59:59Z",
    "createdBy": "creator@example.com",
    "email": "observer@example.com",
    "name": "Observer Name",
    "surnames": "Observer Surnames",
    "notification": {
      "id": "a6f16f42-8e65-4c6f-8253-ad6ded8ae555",
      "notificationId": "notif-345678",
      "status": "PENDING",
      "createdAt": "2023-10-23T10:34:59.483Z",
      "updatedAt": "2023-10-23T10:34:59.483Z"
    }
  }
}

notification.status can also be BOUNCED when the message could not be delivered.

Legal Entity Signed Webhook

Sent when the legal entity signers of a signature request are automatically signed on activation:

{
  "operationType": "SIGNATURE_REQUESTS",
  "data": {
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "signerIds": [
      "b7a16f42-8e65-4c6f-8253-ad6ded8ae666"
    ],
    "signedAt": "2023-10-23T10:34:59.483Z"
  }
}

Note: although this notification is routed using its own webhook configuration entry, the operationType value carried in the payload is currently SIGNATURE_REQUESTS rather than a dedicated value; do not rely on operationType alone to distinguish it from a regular signature request status change — use the presence of signerIds and signedAt instead.

Report Webhook

For report generation operations, the JSON payload is structured as follows:

{
  "operationType": "REPORTS",
  "data": {
    "processId": "1d6d735d-0383-42d1-bfb9-6d4cf71aa739",
    "documentId": "57081c08-08e7-4d7e-b10a-8a98d7b1b3bd",
    "reportUrl": "https://example.com/reports/final.pdf",
    "reportPackageUrl": "https://example.com/reports/final.zip"
  }
}

All identifiers (e.g., signatureRequestId) are UUIDs.

Configuration & Security

The webhook notifications are fully configurable at the client level, allowing you to specify the endpoint(s) where all webhook calls will be sent. This configuration is optional and enables you to direct notifications to the URLs of your choice.

Additionally, each signature request can declare its own webhookUris (see Create signature request). When a signature request has webhookUris configured, all its events (signature request, document, signature/validator/observer notifications and legal entity signed) are delivered only to those URIs for the duration of that signature request, instead of the client-level URLs described above. Signature requests without webhookUris keep using the client-level configuration.

For example, you can configure the webhook URL for signature request notifications as:

http://example.com/signature-requests/callback

And for document notifications:

http://example.com/signature-documents/callback

To ensure secure communication, a security token must be provided by the client (via email or direct communication). We then include this token in our webhook configuration. Every webhook request sent from our platform to your endpoint will include the standardized Authorization header with the following format:

Bearer ${client_token}

For example, a webhook HTTP request may look like this:

POST /signature-requests/callback HTTP/1.1
Host: example.com
Authorization: Bearer abcdef1234567890
Content-Type: application/json

{
  "operationType": "SIGNATURE_REQUESTS",
  "data": {
    "signatureRequestId": "4c33124e-d444-4e97-bbaa-50375c364aca",
    "status": "ACTIVE"
  }
}

This mechanism ensures that your API can verify the authenticity of each webhook request by checking the Authorization header against the token that you have provided.