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

# Webhooks

> Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta

# Webhooks

Los webhooks de Whaapy te permiten recibir notificaciones en tiempo real cuando ocurren eventos en tu cuenta. En lugar de hacer polling constante, configura un endpoint HTTP y recibe actualizaciones automáticamente.

***

## ¿Por qué usar Webhooks?

<CardGroup cols={3}>
  <Card title="Tiempo Real" icon="bolt">
    Recibe eventos al instante, sin delays
  </Card>

  <Card title="Eficiente" icon="gauge-high">
    Sin polling constante a nuestra API
  </Card>

  <Card title="Escalable" icon="arrows-up-down">
    Procesa miles de eventos sin problemas
  </Card>
</CardGroup>

***

## Crear un Webhook

<Note>
  Necesitas un endpoint HTTPS público para recibir webhooks. Para desarrollo local, usa herramientas como [ngrok](https://ngrok.com).
</Note>

**Endpoint**: `POST /user-webhooks`

```bash theme={null}
curl -X POST https://api.whaapy.com/user-webhooks \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi Webhook de Producción",
    "url": "https://mi-servidor.com/webhooks/whaapy",
    "events": ["message.received", "message.sent", "conversation.created"],
    "metadata": {
      "description": "Webhook para sincronizar con CRM"
    }
  }'
```

### Parámetros

| Campo      | Tipo      | Requerido | Descripción                                                                  |
| ---------- | --------- | --------- | ---------------------------------------------------------------------------- |
| `name`     | string    | Sí        | Nombre descriptivo del webhook                                               |
| `url`      | string    | Sí        | URL HTTPS donde recibirás los eventos                                        |
| `events`   | string\[] | Sí        | Lista de eventos a suscribir (ver [Eventos](/api-reference/webhooks/events)) |
| `metadata` | object    | No        | Datos adicionales para tu referencia                                         |

### Response

```json theme={null}
{
  "data": {
    "id": "wh-uuid",
    "name": "Mi Webhook de Producción",
    "url": "https://mi-servidor.com/webhooks/whaapy",
    "events": ["message.received", "message.sent", "conversation.created"],
    "secret": "a1b2c3d4e5f6...",
    "isActive": true,
    "failureCount": 0,
    "createdAt": "2025-01-15T10:00:00Z"
  },
  "message": "Webhook created successfully"
}
```

<Warning>
  **Guarda el `secret` de forma segura.** Lo necesitarás para [verificar la firma](/api-reference/webhooks/security) de los webhooks. No podrás verlo de nuevo.
</Warning>

***

## Estructura del Payload

Todos los webhooks que recibirás tienen esta estructura base:

```json theme={null}
{
  "event": "message.received",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "businessId": "uuid-del-negocio",
  "data": {
    // Datos específicos del evento
  }
}
```

| Campo        | Tipo   | Descripción                             |
| ------------ | ------ | --------------------------------------- |
| `event`      | string | Tipo de evento (ej: `message.received`) |
| `timestamp`  | string | Fecha/hora ISO 8601 del evento          |
| `businessId` | string | UUID de tu negocio                      |
| `data`       | object | Datos específicos del evento            |

Ver [Payloads](/api-reference/webhooks/payloads) para ejemplos detallados de cada evento.

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Eventos Disponibles" icon="list" href="/api-reference/webhooks/events">
    Lista completa de eventos que puedes suscribir
  </Card>

  <Card title="Estructura de Payloads" icon="code" href="/api-reference/webhooks/payloads">
    Ejemplos detallados de cada tipo de evento
  </Card>

  <Card title="Seguridad" icon="shield-check" href="/api-reference/webhooks/security">
    Cómo verificar la autenticidad de los webhooks
  </Card>

  <Card title="Gestión" icon="gear" href="/api-reference/webhooks/management">
    Actualizar, probar y eliminar webhooks
  </Card>
</CardGroup>