Webhooks

Los webhooks permiten que Emify notifique a tu sistema cuando ocurre un evento, en lugar de que consultes el estado por polling. Cuando se produce un evento suscrito, Emify envía una petición HTTP POST con el detalle en formato JSON a la URL que configures. El webhook es de tu cuenta, no de cada empresa: hay uno solo, y recibe los eventos de todas tus empresas, incluidas las que des de alta después. Cada notificación trae el campo companyId, que indica de qué empresa viene el evento.

Antes el webhook se configuraba por empresa, en /api/companies/{company_id}/webhooks. Esas rutas ya no existen y las suscripciones por empresa se dieron de baja: si tenías alguna, volvé a configurar tu webhook en /api/webhooks.

Funcionamiento

Registrás una URL

Indicás el endpoint HTTPS de tu sistema y los eventos que querés recibir. Vale para todas tus empresas.

Ocurre un evento

Cuando se dispara un evento suscrito, Emify envía un POST con el payload a tu URL.

Confirmás la recepción

Tu servidor responde con un código 2xx. Si no, Emify reintenta la entrega.

Eventos disponibles

Evento	Descripción
`ISE`	Cambio en el estado de un comprobante electrónico.
`REC`	Recepción de un comprobante de compra.
`CER`	Aviso de próximo vencimiento de un certificado digital.
`ENU`	Aviso de vencimiento o baja disponibilidad de folios (CAF).

Consulta el catálogo vigente en cualquier momento:

curl https://api.emify.co/api/webhooks/events \
  -H "X-Api-Key: tu_api_key"

Configurar un webhook

Registra la URL de destino y los eventos a recibir:

curl -X POST https://api.emify.co/api/webhooks \
  -H "X-Api-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-sistema.com/callback",
    "events": ["ISE", "CER"],
    "description": "Notificaciones de producción"
  }'

Los endpoints GET, PUT y DELETE sobre /api/webhooks permiten consultar, actualizar y eliminar la configuración. Si tu cuenta ya tiene un webhook, un nuevo POST responde 409: usá PUT para cambiarlo.

Configurar el webhook exige una API key sin restricción de empresas. Como el webhook recibe los datos de todas tus empresas, una key limitada a algunas responde 403. El catálogo de eventos (/api/webhooks/events) lo puede consultar cualquier key.

Payload de la notificación

Cada evento envía un POST con un cuerpo JSON que incluye companyId, la empresa donde ocurrió el evento. Como el webhook es uno solo para toda tu cuenta, ese campo es el que te permite distinguir de qué empresa viene cada notificación. Por ejemplo, el evento ISE (cambio de estado de un comprobante):

{
  "invoiceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "APR",
  "number": 1234,
  "companyId": "36"
}

Los valores de status se explican en Ciclo de vida de un documento.

Reintentos

Si tu endpoint no responde 2xx, Emify reintenta la entrega. La entrega se intenta hasta 4 veces en total, con esperas crecientes entre reintentos:

Reintento	Espera
1º	1 minuto
2º	5 minutos
3º	30 minutos

Tras el cuarto intento fallido, la entrega se marca como fallida y no se vuelve a intentar.

Diseña tu handler para ser idempotente: un mismo evento puede entregarse más de una vez.

Buenas prácticas

Responde rápido con un código 2xx y procesa la carga de forma asíncrona (por ejemplo, con una cola).
Valida el origen del evento antes de procesarlo.
Trata las entregas como idempotentes usando el identificador del recurso incluido en el payload.

Primeros pasos

Conceptos

Funcionamiento

Eventos disponibles

Configurar un webhook

Payload de la notificación

Reintentos

Buenas prácticas

​Funcionamiento

​Eventos disponibles

​Configurar un webhook

​Payload de la notificación

​Reintentos

​Buenas prácticas

Funcionamiento

Eventos disponibles

Configurar un webhook

Payload de la notificación

Reintentos

Buenas prácticas