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

# Webhooks

> Aprenda cómo recibir eventos de Notifique en su sistema en tiempo real.

<Tip>
  Un webhook es el **timbre** de tu servidor: cuando sucede algo en Notifique (mensaje enviado, entregado, respuesta del cliente…), lo hacemos sonar con un JSON POST en tu URL.
</Tip>

## ¿Qué es un webhook?

Es una **URL HTTPS** en su sistema que recibe alertas automáticas de Notifique. En lugar de sondear la API y preguntar "¿se entregó?", **espera a que llegue la alerta**.

Piense en ello como una notificación automática, pero para su backend.

## ¿Para qué sirve?

Con los webhooks puedes:

* **Saber de inmediato** cuándo se envió, entregó, leyó o falló un mensaje
* **Automatizar** pedidos, CRM, facturación y bots sin consultar el panel
* **Procesar** los mensajes que te envían los clientes (WhatsApp, Telegram, SMS)
* **Monitorizar** conexión de instancia (QR, conectado, desconectado)
* **Seguir** clics en enlaces cortos y eventos de formularios

## ¿Cuándo usarlo?

| Situación                                               | ¿Usar webhook?    |
| ------------------------------------------------------- | ----------------- |
| Necesita reaccionar **de inmediato** cuando algo cambia | **Sí**            |
| Quiere automatizar (bot, ERP, su sistema)               | **Sí**            |
| Solo consulta el panel de vez en cuando                 | No es obligatorio |

## Cómo configurar

### 1. Prepare su endpoint

Cree una ruta **HTTPS** que acepte **POST** JSON y responda **2xx** rápidamente.

Ejemplo: `https://yoursite.com/webhooks/notifique`

Si el procesamiento es pesado, haga **cola** de su lado y devuelva 200 inmediatamente. Como abrir el timbre y atender la visita más tarde.

### 2. Regístrese en el panel

Abra **Desarrollador → Webhooks**, cree un webhook y seleccione los [eventos](#eventos-por-canal) que le interesen.

También puede registrarse a través de la API con ámbitos `webhooks:manage` y `webhooks:read`. ¿Necesita una clave? Consulte [Claves API](/es/guides/api-key/index).

**Guarde el secreto** de la respuesta. Lo usa para validar cada POST.

### 3. Validar la firma

Cada POST incluye `X-Notifique-Signature` y `X-Notifique-Timestamp`. Calcule HMAC-SHA256 del secreto con `{timestamp}.{raw body}` y rechace marcas de tiempo fuera de **5 minutos**.

Detalles en la sección [Encabezados y firma](#encabezados-y-firma) a continuación.

### 4. Manejar reintentos

Si su endpoint falla, lo volvemos a intentar a los **5 min, 30 min y 2 h**. Responda **2xx** rápidamente.

## Sandbox vs producción

* **Sandbox** (`sk_test_...`): mismos nombres de eventos; la carga útil incluye `sandbox: true`
* **Producción** (`sk_live_...`): eventos reales a partir de tráfico en vivo

Simule eventos en **Desarrollador → Bandeja de entrada Sandbox**. Más en [Modo Sandbox](/es/guides/sandbox/index).

## Formato de carga útil

Todas las solicitudes son **POST** con `Content-Type: application/json`. El cuerpo sigue esta estructura:

| Campo           | Tipo                | Descripción                                                                                                                   |
| --------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **event**       | string              | Nombre del evento (ej. `message.sent`, `sms.delivered`).                                                                      |
| **workspaceId** | string              | ID del espacio de trabajo.                                                                                                    |
| **instanceId**  | string              | ID de instancia WhatsApp (vacío para SMS, correo y push).                                                                     |
| **messageId**   | string \| undefined | ID del mensaje en Notifique (cuando aplique); para **`short_link.clicked`** es el **clickEventId** (ID del registro de clic). |
| **timestamp**   | string              | ISO 8601; use para anti-replay (ventana recomendada: 5 min).                                                                  |
| **data**        | object              | Datos específicos del evento (ver cada página de canal abajo).                                                                |

## Encabezados y firma

| Encabezado                | Descripción                                           |
| ------------------------- | ----------------------------------------------------- |
| **Content-Type**          | `application/json`                                    |
| **X-Webhook-Event**       | Nombre del evento.                                    |
| **X-Notifique-Timestamp** | Marca de tiempo en segundos (Unix) usada en la firma. |
| **X-Notifique-Signature** | Firma: `t={timestamp},v1={hash}`.                     |
| **X-Workspace-Id**        | ID del espacio de trabajo.                            |

* **Cálculo HMAC:** `hash = HMAC-SHA256(secret, timestamp + "." + body)` (body = cuerpo POST sin procesar).
* **Anti-replay:** Rechace solicitudes con marca de tiempo fuera de una ventana (ej. 5 minutos).

## Mensajes entrantes

Para procesar lo que el **cliente envió** (WhatsApp, Telegram, SMS):

1. Suscríbase al evento en el webhook
2. Configure entrantes en **Configuración → Mensajes recibidos**

El webhook le avisa con un resumen. Para **descargar medios** (audio, imagen, documento) en WhatsApp, use `inboundId` vía API. Guía completa: [Mensajes entrantes y respuestas](/es/guides/webhooks/mensagens-recebidas-e-respostas).

## Buenas prácticas

1. **HTTPS siempre** en la URL registrada
2. **Responda 2xx rápido** y procese en segundo plano
3. **Valide la firma** en cada POST
4. **Suscríbase solo a eventos** que su integración consume

Más detalles: [Seguridad y confiabilidad](/es/guides/conceitos/seguranca-e-confiabilidade).

## Eventos por canal

Cada canal tiene sus propios eventos. Seleccione solo lo que necesita:

<CardGroup cols={2}>
  <Card title="WhatsApp" icon="whatsapp" href="/es/whatsapp-api/como-funciona/eventos-do-webhooks">
    Envío, entrega, entrantes e instancia
  </Card>

  <Card title="SMS" icon="comment-sms" href="/es/sms-api/como-funciona/eventos-do-webhooks">
    Envío, DLR, MO y respuestas
  </Card>

  <Card title="Telegram" icon="paper-plane" href="/es/telegram-api/como-funciona/eventos-do-webhooks">
    Envío, entrantes e instancia
  </Card>

  <Card title="Instagram" icon="instagram" href="/es/instagram-api/como-funciona/eventos-do-webhooks">
    Envío, comentarios y entrantes
  </Card>

  <Card title="Email" icon="envelope" href="/es/emails-api/como-funciona/eventos-do-webhooks">
    Envío, apertura, clic y rebote
  </Card>

  <Card title="Push" icon="bell" href="/es/push-api/como-funciona/eventos-do-webhooks">
    Envío, entrega y clic
  </Card>

  <Card title="RCS" icon="mobile-screen" href="/es/rcs-api/como-funciona/eventos-do-webhooks">
    Envío, entrega y fallo
  </Card>

  <Card title="Voice" icon="phone" href="/es/voice-api/como-funciona/eventos-do-webhooks">
    Llamadas y grabaciones
  </Card>

  <Card title="Formularios" icon="clipboard-list" href="/es/marketing-addons-api/como-funciona/eventos-do-webhooks">
    Suscripción, confirmación y baja
  </Card>

  <Card title="Enlaces cortos" icon="link" href="/es/short-links-api/como-funciona/eventos-do-webhooks">
    Clics y conversiones
  </Card>

  <Card title="Números de teléfono" icon="hashtag" href="/es/phone-numbers-api/como-funciona/eventos-do-webhooks">
    Ciclo de vida del número contratado
  </Card>

  <Card title="Automatizaciones" icon="bolt" href="/es/automations-api/como-funciona/eventos-do-webhooks">
    Ciclo de vida activar, pausar y ejecutar
  </Card>

  <Card title="Plantillas (Meta)" icon="file-lines" href="/es/template-api/como-funciona/eventos-do-webhooks">
    Aprobación, rechazo y categoría
  </Card>
</CardGroup>

<Note>
  Evento de reputación del espacio de trabajo (`trust.score_changed`): consulte [Trust Factor](/es/guides/workspaces/trust-factor#webhook-trustscore_changed).
</Note>

***

## Próximos pasos

* [Empiece aquí](/es/guides/introducao/comece-aqui): envíe su primer mensaje
* [Claves API](/es/guides/api-key/index): credenciales para registrar webhooks vía API