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.
• data: Contains the details of the operation. The content of this field depends on the specific event.

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.

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"
    ]
  }
}

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: READY_TO_SIGN, REJECTED, ERROR.

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"
    ]
  }
}

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.

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.