Webhooks

Los webhooks permiten que Alanube notifique a tu sistema cuando ocurre un evento relevante en una compañía, sin que tengas que consultar periódicamente la API.

Cuando un evento configurado ocurre, Alanube realiza una solicitud HTTP POST a la URL registrada en la compañía y envía el body correspondiente al evento. Si configuraste headers, Alanube los envía en esa misma solicitud.

Eventos disponibles

Configuración

Puedes configurar los webhooks al crear o actualizar una compañía.

• Crear compañía: POST /per/v1/companies
• Actualizar compañía: PATCH /per/v1/companies/{id}

Ejemplo de configuración:

{
  "webhooks": {
    "emissionDocumentFinished": {
      "status": "active",
      "url": "https://api.tu-compania.com/webhooks/emission-finished",
      "headers": {
        "Authorization": "Bearer token-de-tu-sistema",
        "x-company-id": "mi-compania"
      }
    },
    "cancellationDocumentFinished": {
      "status": "active",
      "url": "https://api.tu-compania.com/webhooks/cancellation-finished",
      "headers": {
        "Authorization": "Bearer token-de-tu-sistema"
      }
    }
  }
}

Campos de configuración

Recomendaciones para tu endpoint

• Expón una URL HTTPS capaz de recibir solicitudes POST con Content-Type: application/json.
• Valida los headers configurados, por ejemplo Authorization o x-api-key, para confirmar que la llamada proviene de Alanube.
• Responde con un código HTTP 2xx cuando proceses correctamente la notificación.
• Diseña tu integración para ser idempotente: un mismo evento podría volver a enviarse si el documento se reprocesa manualmente.
• No dependas de una respuesta de Alanube al webhook: la notificación es una llamada saliente desde Alanube hacia tu sistema.

Notas de entrega

Alanube considera enviada la notificación cuando la solicitud HTTP al webhook finaliza correctamente. Si la URL no responde, hay un error de red o el endpoint responde con error HTTP, la notificación se registra como no enviada.