Saltar al contenido
Crear cuenta Ingresar
Menú

API y SDK

Ayuda

Crear cuenta Ingresar
API y SDK
Ayuda
Saltar la navegación de la documentación

Español API 2026-10-22

Documentación · Referencia · API v1 · versión 2026-10-22

Endpoints de webhooks

Las operaciones de Endpoints de webhooks de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.

Ver como Markdown

Endpoints que reciben avisos firmados (Standard Webhooks) cuando un documento cambia.

Los ejemplos son peticiones con cURL. La llave va en TREVOL_API_KEY; los cuerpos de ejemplo son los de la especificación. Los errores comunes están en Errores.

Crear un endpoint de webhooks (máximo 5 por empresa y ambiente)

POST /v1/webhook_endpoints · createWebhookEndpoint

El secret (whsec_…) viene SOLO en esta respuesta. Cada entrega lleva webhook-id (el mismo en cada reintento: deduplica con él), webhook-timestamp y webhook-signature: v1, + base64(HMAC-SHA256(clave, {webhook-id}.{webhook-timestamp}.{cuerpo})), con la clave de los 32 bytes que siguen a whsec_. No usa Idempotency-Key: la respuesta lleva el secreto y no se guarda.

Cuerpo (WebhookEndpointInput, obligatorio)

  • urltextoobligatorio
    https:// con un nombre de dominio (no una IP), sin usuario ni clave, puerto 443 o 1024–65535. En cada intento se resuelve el nombre y se rechaza toda dirección privada o local.
  • descriptiontexto (puede ser null)
  • eventslista de * | invoice.accepted | invoice.rejected | invoice.error | invoice.delivered | invoice.email_bounced | invoice.email_failed | credit_note.accepted | credit_note.rejected | credit_note.error | credit_note.delivered | credit_note.email_bounced | credit_note.email_failed | debit_note.accepted | debit_note.rejected | debit_note.error | debit_note.delivered | debit_note.email_bounced | debit_note.email_failed | balance.low | numbering.low | numbering.expiring | certificate.expiring | support_document.accepted | support_document.rejected | support_document.error | support_document_adjustment.accepted | support_document_adjustment.rejected | support_document_adjustment.error | equivalent_document.accepted | equivalent_document.rejected | equivalent_document.error | equivalent_document.delivered | equivalent_document.email_bounced | equivalent_document.email_failed | equivalent_document_adjustment.accepted | equivalent_document_adjustment.rejected | equivalent_document_adjustment.error | equivalent_document_adjustment.delivered | equivalent_document_adjustment.email_bounced | equivalent_document_adjustment.email_failed | payroll.accepted | payroll.rejected | payroll.error | payroll_adjustment.accepted | payroll_adjustment.rejected | payroll_adjustment.error | radian_event.accepted | radian_event.rejected | radian_event.errorobligatorio
    Eventos del catálogo (49 tipos, hasta 60 en la lista), o ["*"] para todos (no se mezcla). balance.low, numbering.low y numbering.expiring solo existen en producción (llaves live). webhook.test no se suscribe. Máximo 60.

Respuestas

Estado Qué pasó
201 El endpoint, con su secret (WebhookEndpoint)
409 Error (application/problem+json) (Problem)
422 Error (application/problem+json) (Problem)
Error Error (application/problem+json) (Problem)

POST /v1/webhook_endpoints

cURL
curl -X POST "https://api.trevol.si/v1/webhook_endpoints" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://tu-servidor.co/webhooks/trevol",
  "description": "Producción: facturación",
  "events": [
    "invoice.accepted",
    "invoice.rejected",
    "credit_note.accepted"
  ]
}'

Se administra en Webhooks

Mandar un evento webhook.test solo a este endpoint (debe estar activo)

POST /v1/webhook_endpoints/{id}/test · testWebhookEndpoint

Encola una entrega manual de prueba (3 intentos) y despierta el envío: en segundos llega a tu servidor con la firma de siempre. Hasta 60 por hora. Mira cómo salió en …/deliveries.

Respuestas

Estado Qué pasó
202 La entrega encolada (WebhookDelivery)
409 Error (application/problem+json) (Problem)
429 Error (application/problem+json) (Problem)
Error Error (application/problem+json) (Problem)

POST /v1/webhook_endpoints/{id}/test

cURL
curl -X POST "https://api.trevol.si/v1/webhook_endpoints/we_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/test" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Rotar el secreto

POST /v1/webhook_endpoints/{id}/rotate_secret · rotateWebhookEndpointSecret

El secret (whsec_…) viene SOLO en esta respuesta. Cada entrega lleva webhook-id (el mismo en cada reintento: deduplica con él), webhook-timestamp y webhook-signature: v1, + base64(HMAC-SHA256(clave, {webhook-id}.{webhook-timestamp}.{cuerpo})), con la clave de los 32 bytes que siguen a whsec_. El secreto anterior sigue firmando grace_period_hours (0 a 72; 24 por defecto): durante la gracia cada entrega lleva las dos firmas, separadas por un espacio.

Cuerpo (objeto)

  • grace_period_hoursentero

Respuestas

Estado Qué pasó
200 El endpoint, con el secret nuevo (WebhookEndpoint)
422 Error (application/problem+json) (Problem)
Error Error (application/problem+json) (Problem)

POST /v1/webhook_endpoints/{id}/rotate_secret

cURL
curl -X POST "https://api.trevol.si/v1/webhook_endpoints/we_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/rotate_secret" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "grace_period_hours": 24
}'

Se administra en Webhooks

Los endpoints de webhooks de la empresa y el ambiente

GET /v1/webhook_endpoints · listWebhookEndpoints

Los de la empresa y el ambiente de la llave (máximo 5). Las llaves de lectura ven el esquema y el host de la url, con el camino enmascarado («https://tu-servidor.co/…»): a veces es un secreto. Las de escritura la ven completa.

Respuestas

Estado Qué pasó
200 {object: list, data, has_more, next_cursor} (objeto)
Error Error (application/problem+json) (Problem)

GET /v1/webhook_endpoints

cURL
curl "https://api.trevol.si/v1/webhook_endpoints" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Un endpoint

GET /v1/webhook_endpoints/{id} · retrieveWebhookEndpoint

El endpoint (nunca el secreto: solo se muestra al crear o rotar). Un id de otra empresa o de otro ambiente es 404.

Respuestas

Estado Qué pasó
200 El recurso (WebhookEndpoint)
Error Error (application/problem+json) (Problem)

GET /v1/webhook_endpoints/{id}

cURL
curl "https://api.trevol.si/v1/webhook_endpoints/we_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Las entregas de este endpoint, de la más nueva a la más vieja

GET /v1/webhook_endpoints/{id}/deliveries · listWebhookEndpointDeliveries

Cada intento con su estado HTTP, su error (timeout, http_5xx, blocked_address…) y su duración. Nunca guardamos la respuesta de tu servidor. Se conservan 30 días.

Parámetros

  • limitconsultaentero
  • starting_afterconsultatexto
  • statusconsultapending | sending | succeeded | failed | canceled

Respuestas

Estado Qué pasó
200 {object: list, data, has_more, next_cursor} (objeto)
Error Error (application/problem+json) (Problem)

GET /v1/webhook_endpoints/{id}/deliveries

cURL
curl "https://api.trevol.si/v1/webhook_endpoints/we_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/deliveries?limit=100" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Cambiar la URL, la descripción, los eventos o pausar y reactivar

PATCH /v1/webhook_endpoints/{id} · updateWebhookEndpoint

Solo cambia lo que mandes. status: paused cancela las entregas pendientes; status: enabled reactiva el endpoint (también uno que Trevol desactivó por fallos sostenidos) y pone en cero el contador de fallos. disabled no se puede pedir.

Cuerpo (WebhookEndpointUpdate, obligatorio)

  • urltexto
    https:// con un nombre de dominio (no una IP), sin usuario ni clave, puerto 443 o 1024–65535. En cada intento se resuelve el nombre y se rechaza toda dirección privada o local.
  • descriptiontexto (puede ser null)
  • eventslista de * | invoice.accepted | invoice.rejected | invoice.error | invoice.delivered | invoice.email_bounced | invoice.email_failed | credit_note.accepted | credit_note.rejected | credit_note.error | credit_note.delivered | credit_note.email_bounced | credit_note.email_failed | debit_note.accepted | debit_note.rejected | debit_note.error | debit_note.delivered | debit_note.email_bounced | debit_note.email_failed | balance.low | numbering.low | numbering.expiring | certificate.expiring | support_document.accepted | support_document.rejected | support_document.error | support_document_adjustment.accepted | support_document_adjustment.rejected | support_document_adjustment.error | equivalent_document.accepted | equivalent_document.rejected | equivalent_document.error | equivalent_document.delivered | equivalent_document.email_bounced | equivalent_document.email_failed | equivalent_document_adjustment.accepted | equivalent_document_adjustment.rejected | equivalent_document_adjustment.error | equivalent_document_adjustment.delivered | equivalent_document_adjustment.email_bounced | equivalent_document_adjustment.email_failed | payroll.accepted | payroll.rejected | payroll.error | payroll_adjustment.accepted | payroll_adjustment.rejected | payroll_adjustment.error | radian_event.accepted | radian_event.rejected | radian_event.error
    Eventos del catálogo (49 tipos, hasta 60 en la lista), o ["*"] para todos (no se mezcla). balance.low, numbering.low y numbering.expiring solo existen en producción (llaves live). webhook.test no se suscribe. Máximo 60.
  • statusenabled | paused
    enabled reactiva (también uno desactivado por Trevol) y pone en cero el contador de fallos.

Respuestas

Estado Qué pasó
200 El recurso (WebhookEndpoint)
422 Error (application/problem+json) (Problem)
Error Error (application/problem+json) (Problem)

PATCH /v1/webhook_endpoints/{id}

cURL
curl -X PATCH "https://api.trevol.si/v1/webhook_endpoints/we_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Pausado mientras migramos el servidor",
  "status": "paused"
}'

Se administra en Webhooks

Borrar el endpoint (con sus entregas)

DELETE /v1/webhook_endpoints/{id} · deleteWebhookEndpoint

Tu servidor deja de recibir avisos de inmediato. No se puede deshacer; si solo quieres detenerlo un rato, pausa el endpoint.

Respuestas

Estado Qué pasó
200 {id, object: webhook_endpoint, deleted: true} (DeletedObject)
Error Error (application/problem+json) (Problem)

DELETE /v1/webhook_endpoints/{id}

cURL
curl -X DELETE "https://api.trevol.si/v1/webhook_endpoints/we_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Se administra en Webhooks