Webhooks y catalogo de eventos

Eventos

Configura destinos salientes y entiende que significa cada evento de proceso, OTP, biometria y documento.

Modelo orientado a eventos

Signly usa webhooks como canal principal para sincronizar cambios de estado. Tu integracion debe procesar idempotencia, reintentos y orden parcial de eventos.

Familias de eventos y significado

Proceso

Creación, inicio, cierre, falla, cancelación y vencimiento del proceso.

OTP

Envío, reenvío, validación, fallo y expiración del reto OTP.

Biometria y liveness

Captura, validación o rechazo biométrico, más prueba de vida aprobada o fallida.

Documento

Apertura del documento, firma de campos y trazabilidad del cierre final.

Como interpretar los eventos principales

`PROCESS_CREATED`: el backend acepto el documento y creo al menos un participante con `processId`.
`OTP_SENT` o `OTP_RESENT`: Signly intento entregar el reto de autenticacion por el canal configurado.
`OTP_VERIFIED`: el participante supero la autenticacion OTP y puede avanzar al siguiente paso.
`BIOMETRIC_VERIFIED` o `LIVENESS_VERIFIED`: el flujo de identidad de alto assurance quedo aprobado.
`FIELD_SIGNED`: se diligencio un campo de firma, aceptacion o evidencia dentro del documento.
`PROCESS_COMPLETED`: ya puedes reconciliar cierre, evidencias y documentos finales en tu sistema.
`PROCESS_FAILED`, `PROCESS_CANCELLED` o `PROCESS_EXPIRED`: el flujo quedo interrumpido y requiere tratamiento operativo en tu sistema.

Catalogo operativo de eventos

Listado practico de los eventos que debes reconocer en integracion y operacion. Algunos flujos no emiten todos los eventos; depende del canal de firma y de la politica de identidad configurada.

`PROCESS_CREATED`: el documento fue aceptado y Signly creo el proceso del participante.
`PROCESS_STARTED`: el participante comenzo efectivamente el flujo.
`PROCESS_COMPLETED`: el proceso termino correctamente y ya puedes cerrar conciliacion.
`PROCESS_FAILED`: el proceso termino con error no recuperable o bloqueo funcional.
`PROCESS_CANCELLED`: el proceso fue cancelado manualmente o por politica.
`PROCESS_EXPIRED`: el proceso llego a fecha limite sin completarse.
`OTP_SENT`: se envio el codigo OTP por el canal configurado.
`OTP_RESENT`: se ejecuto un reenvio de OTP.
`OTP_VERIFIED`: el participante valido correctamente el OTP.
`OTP_FAILED`: el OTP fallo por codigo invalido o politica de intentos.
`OTP_EXPIRED`: el reto OTP vencio antes de ser validado.
`BIOMETRIC_STARTED`: comenzo la captura o validacion biometrica.
`BIOMETRIC_VERIFIED`: la biometria fue validada exitosamente.
`BIOMETRIC_FAILED`: la biometria no cumplio validacion.
`LIVENESS_STARTED`: comenzo la prueba de vida.
`LIVENESS_VERIFIED`: la prueba de vida fue aprobada.
`LIVENESS_FAILED`: la prueba de vida fue rechazada o no concluyo.
`DOCUMENT_VIEWED`: el participante abrio el documento.
`FIELD_SIGNED`: se completo un campo de firma, aceptacion o evidencia.

Payload de entrega

Ejemplo representativo de un evento que tu backend puede recibir cuando un proceso termina.

Payload de entrega

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

Buenas practicas de consumo

Responde `2xx` solo cuando tu sistema persista el evento o lo haya entregado a una cola interna.
Guarda `eventId`, `documentId` y `attempt` para asegurar idempotencia.
Si un flujo es sensible para negocio, usa webhooks y una consulta puntual al documento para reconciliar.

Gestion de webhooks

GET /v1/webhooks Lista webhooks del tenant.

POST /v1/webhooks Crea un webhook.

GET /v1/webhooks/{webhookId} Consulta un webhook por ID.

PUT /v1/webhooks/{webhookId} Actualiza descripcion, eventos y retries.

PUT /v1/webhooks/{webhookId}/status Activa o desactiva un webhook.

POST /v1/webhooks/{webhookId}/test Envia un evento de prueba.

DELETE /v1/webhooks/{webhookId} Elimina un webhook.

API Reference

6 endpoints

Cada endpoint incluye método, ruta, descripción funcional, headers, parámetros, campos del body, request de ejemplo y respuestas de éxito/error.

GET /v1/webhooks

Lista webhooks.

Devuelve los webhooks del tenant y soporta filtros por estado, URL y rango de actualizacion.

Headers

Campo	Tipo	Requerido	Descripcion
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Si	Identificador del tenant que contextualiza toda la operacion.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Si	Credencial partner del tenant. Para `KEY` se envia el valor crudo; para `HMAC` el authorizer acepta `HMAC <secret>` o el secreto crudo.

Parametros de query

Campo	Tipo	Requerido	Descripcion
`limit` ex. 10	`integer`	No	Tamano de pagina entre 1 y 100.
`status` ex. ENABLED	`string`	No	Estado `ENABLED` o `DISABLED`.
`sort` ex. -updatedAt	`string`	No	Orden soportado por `updatedAt` o `url`.

Ejemplos de request

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 listados

Webhooks listados · 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

Crea un webhook.

Registra un destino HTTP para recibir eventos de Signly. El servicio ejecuta una validacion corta de conectividad antes de persistir.

Headers

Campo	Tipo	Requerido	Descripcion
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Si	Identificador del tenant que contextualiza toda la operacion.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Si	Credencial partner del tenant. Para `KEY` se envia el valor crudo; para `HMAC` el authorizer acepta `HMAC <secret>` o el secreto crudo.
`Content-Type` ex. application/json	`application/json`	Si	Tipo de payload JSON.

Campos del body

Campo	Tipo	Requerido	Descripcion
`url` ex. https://example.com/signly/webhooks	`string`	Si	Endpoint HTTPS receptor.
`events` ex. ["PROCESS_COMPLETED","OTP_VERIFIED"]	`string[]`	Si	Lista de eventos a suscribir.
`description`	`string`	No	Descripcion operativa del destino.
`customHeaders`	`object`	No	Headers adicionales enviados en cada entrega.
`retries`	`object`	No	Politica de reintentos del webhook.

Ejemplos de request

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 creado

Webhook creado · 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}

Consulta un webhook.

Devuelve configuracion, estado y version del webhook.

Headers

Campo	Tipo	Requerido	Descripcion
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Si	Identificador del tenant que contextualiza toda la operacion.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Si	Credencial partner del tenant. Para `KEY` se envia el valor crudo; para `HMAC` el authorizer acepta `HMAC <secret>` o el secreto crudo.

Parametros de path

Campo	Tipo	Requerido	Descripcion
`webhookId`	`string`	Si	Identificador del webhook.

Ejemplos de request

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 consultado

Webhook consultado · 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}

Actualiza un webhook.

Permite editar descripcion, lista de eventos, retries y timeout. Soporta concurrencia optimista via `If-Match`.

Headers

Campo	Tipo	Requerido	Descripcion
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Si	Identificador del tenant que contextualiza toda la operacion.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Si	Credencial partner del tenant. Para `KEY` se envia el valor crudo; para `HMAC` el authorizer acepta `HMAC <secret>` o el secreto crudo.
`Content-Type` ex. application/json	`application/json`	Si	Tipo de payload JSON.
`If-Match` ex. 3	`integer`	No	Version esperada del recurso.

Parametros de path

Campo	Tipo	Requerido	Descripcion
`webhookId`	`string`	Si	Webhook a modificar.

Campos del body

Campo	Tipo	Requerido	Descripcion
`description`	`string`	No	Nueva descripcion.
`status` ex. DISABLED	`string`	No	Nuevo estado del webhook.
`events`	`string[]`	No	Nueva lista de eventos.

Ejemplos de request

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 actualizado

Webhook actualizado · 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

Version desfasada

Version desfasada · 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

Activa o desactiva un webhook.

Atajo para actualizar solo el estado operativo del webhook.

Headers

Campo	Tipo	Requerido	Descripcion
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Si	Identificador del tenant que contextualiza toda la operacion.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Si	Credencial partner del tenant. Para `KEY` se envia el valor crudo; para `HMAC` el authorizer acepta `HMAC <secret>` o el secreto crudo.
`Content-Type` ex. application/json	`application/json`	Si	Tipo de payload JSON.
`If-Match` ex. 4	`integer`	No	Version esperada.

Parametros de path

Campo	Tipo	Requerido	Descripcion
`webhookId`	`string`	Si	Webhook cuyo estado cambiara.

Campos del body

Campo	Tipo	Requerido	Descripcion
`status` ex. DISABLED	`string`	Si	Nuevo estado `ENABLED` o `DISABLED`.

Ejemplos de request

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

Estado actualizado

Estado actualizado · 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

Envia un evento de prueba.

Dispara un evento sintentico para validar que tu endpoint responda correctamente.

Headers

Campo	Tipo	Requerido	Descripcion
`X-Tenant-Signly` ex. 58bff266-cdad-46db-b373-1b06476146cd	`string`	Si	Identificador del tenant que contextualiza toda la operacion.
`X-Auth-Signly` ex. sk_live_partner_abc123	`string`	Si	Credencial partner del tenant. Para `KEY` se envia el valor crudo; para `HMAC` el authorizer acepta `HMAC <secret>` o el secreto crudo.
`Content-Type` ex. application/json	`application/json`	Si	Tipo de payload JSON.

Parametros de path

Campo	Tipo	Requerido	Descripcion
`webhookId`	`string`	Si	Webhook al que se enviara la prueba.

Ejemplos de request

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

Prueba enviada

Prueba enviada · 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
}