> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emify.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Registrás una URL">
    Indicás el endpoint HTTPS de tu sistema y los eventos que querés recibir.
  </Step>

  <Step title="Ocurre un evento">
    Cuando se dispara un evento suscrito, Emify envía un `POST` con el payload a tu URL.
  </Step>

  <Step title="Confirmás la recepción">
    Tu servidor responde con un código `2xx`. Si no, Emify reintenta la entrega.
  </Step>
</Steps>

## 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:

```bash theme={null}
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:

```bash theme={null}
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):

```json theme={null}
{
  "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](/guias/ciclo-de-vida-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.

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

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