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

# Webhooks

> Suscribe sistemas externos a los eventos—WhatsApp, iMessage y SMS entrantes/salientes, y eventos del sistema.

Los webhooks te permiten enviar eventos en tiempo real a cualquier endpoint externo. Úsalos para sincronizar mensajes con tu CRM, activar automatizaciones en n8n/Make/Zapier o crear backends personalizados.

## Crear una Suscripción de Webhook

<Steps>
  <Step title="Abre tu Ubicación">
    Ve a **Panel → Ubicaciones** y selecciona la ubicación a la que quieres suscribirte.
  </Step>

  <Step title="Abre Configuración">
    Haz clic en la pestaña **Configuración** de esa ubicación.
  </Step>

  <Step title="Crear suscripción">
    Desplázate hasta la sección **Webhooks** y haz clic en **Crear suscripción**.
  </Step>

  <Step title="Completa el formulario">
    Completa el cuadro de diálogo **Crear suscripción** (consulta los campos a continuación).
  </Step>

  <Step title="Guardar">
    Haz clic en **Crear suscripción** para guardar. Si "Enviar un ping de prueba" está habilitado, se enviará un evento ficticio mediante POST a tu endpoint para verificar que funciona.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/goghl-whitelable/d0UJrCwlyc8wzaxE/images/features/assets/images/webhook.png?fit=max&auto=format&n=d0UJrCwlyc8wzaxE&q=85&s=3a5728c9bc59a7bda48b0e6f663725f1" alt="Crear suscripción de webhook" width="2886" height="1862" data-path="images/features/assets/images/webhook.png" />
</Frame>

## Campos de la Suscripción

### Nombre *(obligatorio)*

Una etiqueta legible para que puedas identificar la suscripción más tarde (por ejemplo, `Sincronización CRM`, `Manejador Entrante n8n`).

### URL de Destino

El endpoint HTTPS que recibirá las cargas útiles (payloads) de los eventos.

```text theme={null}
https://example.com/webhooks
```

<Note>
  Tu endpoint debe responder con un código de estado `2xx`. Las respuestas que no sean 2xx se tratan como fallos.
</Note>

### Seleccionar eventos

Elige exactamente qué eventos deben activar un webhook. Puedes combinar canales en una sola suscripción.

#### WhatsApp

* **Entrante** — se recibe un mensaje de WhatsApp
* **Saliente** — se envía un mensaje de WhatsApp

#### iMessage

* **Entrante** — se recibe un iMessage
* **Saliente** — se envía un iMessage

#### SMS

* **Entrante** — se recibe un SMS
* **Saliente** — se envía un SMS

#### Sistema

* **Mensaje fallido** — un mensaje no pudo entregarse (úsalo para lógica de reintentos o alertas)

### Enviar un ping de prueba al crear

Cuando está habilitado, el sistema enviará mediante POST un evento ficticio a tu **URL de Destino** inmediatamente después de crear la suscripción. Úsalo para confirmar que tu endpoint es accesible y que tu manejador analiza las cargas útiles correctamente.

<Tip>
  Déjalo **activado** para la primera suscripción que crees contra un nuevo endpoint.
</Tip>

## Mejores Prácticas

* **Usa una suscripción por integración.** Mantiene los registros y la rotación simples.
* **Verifica con el ping de prueba** antes de confiar en una suscripción en producción.
* **Devuelve `2xx` rápidamente** — delega el trabajo lento a una cola en segundo plano en tu manejador.
* **Sé idempotente.** Los webhooks pueden reentregarse ocasionalmente.
* **Limita por canal.** No te suscribas a eventos que no vas a procesar.

## Gestionar Suscripciones

Desde la sección **Webhooks** en la Configuración de Ubicación puedes:

* Ver todas las suscripciones activas y su fecha de creación
* Eliminar una suscripción que ya no necesites
* Crear suscripciones adicionales para endpoints distintos

## Solución de Problemas

<AccordionGroup>
  <Accordion title="El ping de prueba nunca llegó">
    * Confirma que tu endpoint es accesible públicamente (sin localhost / IPs privadas)
    * Verifica que acepte `POST` y devuelva `2xx`
    * Comprueba que las reglas de firewall/WAF no estén bloqueando la IP
  </Accordion>

  <Accordion title="Los eventos dejaron de dispararse">
    * Asegúrate de que la suscripción no haya sido eliminada
    * Confirma que la ubicación todavía tiene una instancia conectada para el canal
    * Revisa los registros de tu endpoint en busca de respuestas `5xx` (los fallos repetidos pueden deshabilitar la entrega)
  </Accordion>

  <Accordion title="Eventos duplicados">
    Los webhooks son al-menos-una-vez. Usa el ID del evento en la carga útil para deduplicar de tu lado.
  </Accordion>
</AccordionGroup>