Skip to main content
Los webhooks notifican a tu servidor cuando ocurre un evento relevante en Quentli. Cada entrega es una solicitud HTTP POST con un cuerpo JSON UTF-8 y el siguiente sobre:
eventId identifica una entrega. Guarda y deduplica este valor: el mismo evento se puede entregar más de una vez.

Configura un webhook

Crea un endpoint HTTPS desde POST /v1/webhooks. Define solamente los eventos que tu integración procesa.
POST /v1/webhooks
Quentli genera el secreto de firma al crear el webhook. Consúltalo con GET /v1/webhooks/{id}/secret y rótalo con POST /v1/webhooks/{id}/secret/rotate.

Verificación de firma

Quentli firma cada entrega con HMAC SHA-256 usando el cuerpo exacto de la solicitud y un timestamp. La firma se envía en estos headers:
El valor firmado es:
Para verificar la firma, usa el cuerpo crudo de la solicitud antes de parsearlo como JSON, calcula el HMAC con tu secreto y compara el resultado en tiempo constante. Recomendamos rechazar timestamps con más de 5 minutos de diferencia para reducir el riesgo de reenvíos. Guarda el secreto de tu endpoint en QUENTLI_WEBHOOK_SECRET. Los siguientes ejemplos validan la firma antes de leer el JSON.

Entrega y reintentos

  • Responde 2xx en menos de 10 segundos para confirmar la entrega.
  • Las respuestas no 2xx, timeouts y errores de conexión se reintentan hasta ocho veces, después del primer intento.
  • Los reintentos se programan después de 2 segundos, 10 segundos, 5 minutos, 20 minutos, 1 hora, 5 horas, 1 día y 3 días.
  • No asumas orden entre eventos. Usa eventId para deduplicar y consulta el estado actual del recurso si recibes eventos fuera de orden.
  • Puedes consultar el historial en GET /v1/webhook-events y reintentar una entrega con POST /v1/webhook-events/{id}/retry.

Eventos disponibles

Cada página de payload describe el cuerpo completo de la entrega, incluidos los campos opcionales y anulables.