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.

Funcionamiento

Registrás una URL

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

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/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.

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