Webhooks and event catalog

Events

Configure outbound destinations and understand what each process, OTP, biometric, and document event means.

Event-driven model

Signly uses webhooks as the primary channel to synchronize state changes. Your integration should handle idempotency, retries, and partial ordering.

Event families and meaning

Process

Creation, start, completion, failure, cancellation, and expiration of the process.

OTP

Send, resend, validation, failure, and expiration of the OTP challenge.

Biometric and liveness

Biometric capture, validation, or rejection, plus approved or failed liveness.

Document

Document open, field signing, and final completion traceability.

How to interpret the main events

`PROCESS_CREATED`: the backend accepted the document and created at least one participant with a `processId`.
`OTP_SENT` or `OTP_RESENT`: Signly attempted to deliver the authentication challenge through the configured channel.
`OTP_VERIFIED`: the participant passed OTP authentication and can move to the next step.
`BIOMETRIC_VERIFIED` or `LIVENESS_VERIFIED`: the higher-assurance identity flow was approved.
`FIELD_SIGNED`: a signature, acceptance, or evidence field was completed inside the document.
`PROCESS_COMPLETED`: you can now reconcile completion, evidence, and final documents in your system.
`PROCESS_FAILED`, `PROCESS_CANCELLED`, or `PROCESS_EXPIRED`: the flow was interrupted and requires operational handling in your system.

Operational event catalog

Practical list of the events you should recognize in integration and operations. Not every flow emits every event; it depends on the signing channel and configured identity policy.

`PROCESS_CREATED`: the document was accepted and Signly created the participant process.
`PROCESS_STARTED`: the participant effectively started the flow.
`PROCESS_COMPLETED`: the process finished correctly and you can close reconciliation.
`PROCESS_FAILED`: the process ended with a non-recoverable error or functional block.
`PROCESS_CANCELLED`: the process was cancelled manually or by policy.
`PROCESS_EXPIRED`: the process reached its deadline without completion.
`OTP_SENT`: the OTP code was sent through the configured channel.
`OTP_RESENT`: an OTP resend was executed.
`OTP_VERIFIED`: the participant successfully validated the OTP.
`OTP_FAILED`: the OTP failed because of an invalid code or attempts policy.
`OTP_EXPIRED`: the OTP challenge expired before being validated.
`BIOMETRIC_STARTED`: biometric capture or validation started.
`BIOMETRIC_VERIFIED`: biometric validation succeeded.
`BIOMETRIC_FAILED`: biometric validation did not pass.
`LIVENESS_STARTED`: the liveness challenge started.
`LIVENESS_VERIFIED`: the liveness challenge was approved.
`LIVENESS_FAILED`: the liveness challenge was rejected or did not complete.
`DOCUMENT_VIEWED`: the participant opened the document.
`FIELD_SIGNED`: a signature, acceptance, or evidence field was completed.

Delivery payload

Representative example of an event your backend can receive when a process finishes.

Delivery payload

{
  "eventId": "evt_01J8XQ7M8VW2A6G2B0N7J5AZ7Q",
  "type": "PROCESS_COMPLETED",
  "occurredAt": "2026-04-23T14:21:33Z",
  "tenantId": "58bff266-cdad-46db-b373-1b06476146cd",
  "documentId": "0e51e6ee-4643-4381-97e0-5164c00a0142",
  "participantId": "a244be1a-98c5-4faa-bcb7-55218983a731",
  "attempt": 1,
  "data": {
    "status": "COMPLETED",
    "templateId": "3f34581a-5b4a-4068-ab72-5f2b36611fa1",
    "completedAt": "2026-04-23T14:21:31Z"
  }
}

Consumption best practices

Return `2xx` only after your system has persisted the event or delivered it into an internal queue.
Store `eventId`, `documentId`, and `attempt` to guarantee idempotency.
If a flow is business-critical, use webhooks plus targeted document lookups for reconciliation.

Webhook management

GET /v1/webhooks Lists tenant webhooks.

POST /v1/webhooks Creates a webhook.

GET /v1/webhooks/{webhookId} Gets a webhook by ID.

PUT /v1/webhooks/{webhookId} Updates description, events, and retries.

PUT /v1/webhooks/{webhookId}/status Activates or deactivates a webhook.

POST /v1/webhooks/{webhookId}/test Sends a test event.

DELETE /v1/webhooks/{webhookId} Deletes a webhook.

API Reference

6 endpoints

Each endpoint includes method, path, functional description, headers, parameters, body fields, request example, and success/error responses.

GET /v1/webhooks

Lists webhooks.

Returns tenant webhooks and supports filters by status, URL, and update range.

Headers

Field	Type	Required	Description
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Yes	Tenant identifier that scopes the entire operation.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Yes	Tenant partner credential. For `KEY` send the raw value; for `HMAC` the authorizer accepts `HMAC <secret>` or the raw secret.

Query Params

Field	Type	Required	Description
`limit` ex. 10	`integer`	No	Page size between 1 and 100.
`status` ex. ENABLED	`string`	No	Status `ENABLED` or `DISABLED`.
`sort` ex. -updatedAt	`string`	No	Supported sort by `updatedAt` or `url`.

Request examples

cURL

curl -X GET "https://api.signly.apologs.com/v1/webhooks?limit=10&sort=-updatedAt" \
  -H "X-Tenant-Signly: 58bff266-cdad-46db-b373-1b06476146cd" \
  -H "X-Auth-Signly: sk_live_partner_abc123"

200 OK

Webhooks listed

Webhooks listed · 200 OK

{
  "success": true,
  "status": 200,
  "code": "webhooks_listed",
  "message": "Webhooks listed.",
  "data": [
    {
      "webhookId": "wh_01J8XQAGF9E7T7N2G4G6M5J1RP",
      "url": "https://example.com/signly/webhooks",
      "status": "ENABLED",
      "version": 3
    }
  ],
  "pagination": null,
  "meta": {
    "request_id": "req_01J8XQ7M8VW2A6G2B0N7J5AZ7Q",
    "timestamp": "2026-04-23T15:00:00Z",
    "api_version": "v1",
    "tenant_id": "58bff266-cdad-46db-b373-1b06476146cd"
  },
  "error": null
}

POST /v1/webhooks

Creates a webhook.

Registers an HTTP destination to receive Signly events. The service performs a short connectivity validation before persisting.

Headers

Field	Type	Required	Description
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Yes	Tenant identifier that scopes the entire operation.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Yes	Tenant partner credential. For `KEY` send the raw value; for `HMAC` the authorizer accepts `HMAC <secret>` or the raw secret.
`Content-Type` ex. application/json	`application/json`	Yes	JSON payload content type.

Body Fields

Field	Type	Required	Description
`url` ex. https://example.com/signly/webhooks	`string`	Yes	Receiving HTTPS endpoint.
`events` ex. ["PROCESS_COMPLETED","OTP_VERIFIED"]	`string[]`	Yes	List of events to subscribe.
`description`	`string`	No	Operational description for the destination.
`customHeaders`	`object`	No	Additional headers sent on every delivery.
`retries`	`object`	No	Webhook retry policy.

Request examples

cURL

curl -X POST "https://api.signly.apologs.com/v1/webhooks" \
  -H "X-Tenant-Signly: 58bff266-cdad-46db-b373-1b06476146cd" \
  -H "X-Auth-Signly: sk_live_partner_abc123" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/signly/webhooks",
  "description": "Eventos principales del proceso",
  "events": ["PROCESS_COMPLETED", "OTP_VERIFIED", "DOCUMENT_VIEWED"],
  "customHeaders": { "X-Client-Auth": "abc123" },
  "retries": { "maxAttempts": 3, "backoff": "exponential" },
  "httpTimeoutMs": 5000
}'

201 Created

Webhook created

Webhook created · 201 Created

{
  "success": true,
  "status": 201,
  "code": "webhook_created",
  "message": "Webhook created.",
  "data": {
    "webhookId": "wh_01J8XQAGF9E7T7N2G4G6M5J1RP",
    "url": "https://example.com/signly/webhooks",
    "status": "ENABLED",
    "version": 1
  },
  "pagination": null,
  "meta": {
    "request_id": "req_01J8XQ7M8VW2A6G2B0N7J5AZ7Q",
    "timestamp": "2026-04-23T15:00:00Z",
    "api_version": "v1",
    "tenant_id": "58bff266-cdad-46db-b373-1b06476146cd"
  },
  "error": null
}

GET /v1/webhooks/{webhookId}

Gets a webhook.

Returns webhook configuration, status, and version.

Headers

Field	Type	Required	Description
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Yes	Tenant identifier that scopes the entire operation.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Yes	Tenant partner credential. For `KEY` send the raw value; for `HMAC` the authorizer accepts `HMAC <secret>` or the raw secret.

Path Params

Field	Type	Required	Description
`webhookId`	`string`	Yes	Webhook identifier.

Request examples

cURL

curl -X GET "https://api.signly.apologs.com/v1/webhooks/wh_01J8XQAGF9E7T7N2G4G6M5J1RP" \
  -H "X-Tenant-Signly: 58bff266-cdad-46db-b373-1b06476146cd" \
  -H "X-Auth-Signly: sk_live_partner_abc123"

200 OK

Webhook fetched

Webhook fetched · 200 OK

{
  "success": true,
  "status": 200,
  "code": "webhook_fetched",
  "message": "Webhook fetched.",
  "data": {
    "webhookId": "wh_01J8XQAGF9E7T7N2G4G6M5J1RP",
    "url": "https://example.com/signly/webhooks",
    "status": "ENABLED",
    "events": ["PROCESS_COMPLETED", "OTP_VERIFIED"],
    "version": 3
  },
  "pagination": null,
  "meta": {
    "request_id": "req_01J8XQ7M8VW2A6G2B0N7J5AZ7Q",
    "timestamp": "2026-04-23T15:00:00Z",
    "api_version": "v1",
    "tenant_id": "58bff266-cdad-46db-b373-1b06476146cd"
  },
  "error": null
}

PUT /v1/webhooks/{webhookId}

Updates a webhook.

Allows editing description, event list, retries, and timeout. Supports optimistic concurrency through `If-Match`.

Headers

Field	Type	Required	Description
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Yes	Tenant identifier that scopes the entire operation.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Yes	Tenant partner credential. For `KEY` send the raw value; for `HMAC` the authorizer accepts `HMAC <secret>` or the raw secret.
`Content-Type` ex. application/json	`application/json`	Yes	JSON payload content type.
`If-Match` ex. 3	`integer`	No	Expected resource version.

Path Params

Field	Type	Required	Description
`webhookId`	`string`	Yes	Webhook to modify.

Body Fields

Field	Type	Required	Description
`description`	`string`	No	New description.
`status` ex. DISABLED	`string`	No	New webhook status.
`events`	`string[]`	No	New event list.

Request examples

cURL

curl -X PUT "https://api.signly.apologs.com/v1/webhooks/wh_01J8XQAGF9E7T7N2G4G6M5J1RP" \
  -H "X-Tenant-Signly: 58bff266-cdad-46db-b373-1b06476146cd" \
  -H "X-Auth-Signly: sk_live_partner_abc123" \
  -H "Content-Type: application/json" \
  -H "If-Match: 3" \
  -d '{
  "description": "Eventos core de produccion",
  "events": ["PROCESS_COMPLETED", "PROCESS_FAILED", "OTP_VERIFIED"]
}'

200 OK

Webhook updated

Webhook updated · 200 OK

{
  "success": true,
  "status": 200,
  "code": "webhook_updated",
  "message": "Webhook updated.",
  "data": {
    "webhookId": "wh_01J8XQAGF9E7T7N2G4G6M5J1RP",
    "status": "ENABLED",
    "version": 4
  },
  "pagination": null,
  "meta": {
    "request_id": "req_01J8XQ7M8VW2A6G2B0N7J5AZ7Q",
    "timestamp": "2026-04-23T15:00:00Z",
    "api_version": "v1",
    "tenant_id": "58bff266-cdad-46db-b373-1b06476146cd"
  },
  "error": null
}

412 Precondition Failed

Stale version

Stale version · 412 Precondition Failed

{
  "success": false,
  "status": 412,
  "code": "precondition_failed",
  "message": "Webhook version mismatch.",
  "data": null,
  "pagination": null,
  "meta": {
    "request_id": "req_01J8XQ7M8VW2A6G2B0N7J5AZ7Q",
    "timestamp": "2026-04-23T15:00:00Z",
    "api_version": "v1",
    "tenant_id": "58bff266-cdad-46db-b373-1b06476146cd"
  },
  "error": {
    "type": "concurrency",
    "details": { "expectedVersion": 3 }
  }
}

PUT /v1/webhooks/{webhookId}/status

Activates or deactivates a webhook.

Shortcut to update only the webhook operational status.

Headers

Field	Type	Required	Description
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Yes	Tenant identifier that scopes the entire operation.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Yes	Tenant partner credential. For `KEY` send the raw value; for `HMAC` the authorizer accepts `HMAC <secret>` or the raw secret.
`Content-Type` ex. application/json	`application/json`	Yes	JSON payload content type.
`If-Match` ex. 4	`integer`	No	Expected version.

Path Params

Field	Type	Required	Description
`webhookId`	`string`	Yes	Webhook whose status will change.

Body Fields

Field	Type	Required	Description
`status` ex. DISABLED	`string`	Yes	New status `ENABLED` or `DISABLED`.

Request examples

cURL

curl -X PUT "https://api.signly.apologs.com/v1/webhooks/wh_01J8XQAGF9E7T7N2G4G6M5J1RP/status" \
  -H "X-Tenant-Signly: 58bff266-cdad-46db-b373-1b06476146cd" \
  -H "X-Auth-Signly: sk_live_partner_abc123" \
  -H "Content-Type: application/json" \
  -H "If-Match: 4" \
  -d '{ "status": "DISABLED" }'

200 OK

Status updated

Status updated · 200 OK

{
  "success": true,
  "status": 200,
  "code": "webhook_status_updated",
  "message": "Webhook disabled.",
  "data": {
    "webhookId": "wh_01J8XQAGF9E7T7N2G4G6M5J1RP",
    "status": "DISABLED",
    "version": 5
  },
  "pagination": null,
  "meta": {
    "request_id": "req_01J8XQ7M8VW2A6G2B0N7J5AZ7Q",
    "timestamp": "2026-04-23T15:00:00Z",
    "api_version": "v1",
    "tenant_id": "58bff266-cdad-46db-b373-1b06476146cd"
  },
  "error": null
}

POST /v1/webhooks/{webhookId}/test

Sends a test event.

Triggers a synthetic event to validate that your endpoint responds correctly.

Headers

Field	Type	Required	Description
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Yes	Tenant identifier that scopes the entire operation.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Yes	Tenant partner credential. For `KEY` send the raw value; for `HMAC` the authorizer accepts `HMAC <secret>` or the raw secret.
`Content-Type` ex. application/json	`application/json`	Yes	JSON payload content type.

Path Params

Field	Type	Required	Description
`webhookId`	`string`	Yes	Webhook to which the test will be sent.

Request examples

cURL

curl -X POST "https://api.signly.apologs.com/v1/webhooks/wh_01J8XQAGF9E7T7N2G4G6M5J1RP/test" \
  -H "X-Tenant-Signly: 58bff266-cdad-46db-b373-1b06476146cd" \
  -H "X-Auth-Signly: sk_live_partner_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "type": "signly.webhook_test", "tenantId": "58bff266-cdad-46db-b373-1b06476146cd" }'

200 OK

Test sent

Test sent · 200 OK

{
  "success": true,
  "status": 200,
  "code": "webhook_test_sent",
  "message": "Test event delivered.",
  "data": {
    "webhookId": "wh_01J8XQAGF9E7T7N2G4G6M5J1RP",
    "deliveryStatus": "DELIVERED",
    "attempt": 1
  },
  "pagination": null,
  "meta": {
    "request_id": "req_01J8XQ7M8VW2A6G2B0N7J5AZ7Q",
    "timestamp": "2026-04-23T15:00:00Z",
    "api_version": "v1",
    "tenant_id": "58bff266-cdad-46db-b373-1b06476146cd"
  },
  "error": null
}