Webhooks

Recibe notificaciones en tiempo real sobre tus documentos, compras, certificados y folios.

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.

Funcionamiento

1. Registrás una URL

   Indicás el endpoint HTTPS de tu sistema y los eventos que querés recibir.

2. Ocurre un evento

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

3. 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/companies/{company_id}/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/companies/{company_id}/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/companies/{company_id}/webhooks permiten consultar, actualizar y eliminar la configuración.

Payload de la notificación

Cada evento envía un POST con un cuerpo JSON. 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.