# Webhooks

Recibe los eventos de chats y llamadas de un cliente en tu propio endpoint, firmados y verificables

> Full REST + WebSocket API reference: https://api.happ.tools/reference

Recibe eventos de chats y llamadas en tiempo real en tu propio servidor: Happ envía JSON por POST cuando ocurre algo, para que puedas impulsar avisos en Slack, búsquedas en el CRM, analíticas o flujos de trabajo personalizados.

<WebhooksPageDemo />

## Conectar [#connect]

1. Abre el catálogo de **Integraciones** y haz clic en **Conectar** en **Webhook de chat** o **Webhook de llamadas**.
2. En el modal, introduce tu **URL del Webhook**: el endpoint HTTPS que recibe los eventos.
3. Opcionalmente define un **Secreto del webhook** para verificar las solicitudes.
4. Haz clic en **Conectar**.

No hay una página aparte de webhooks, ni interruptores de suscripción a eventos, ni registro de entregas en la aplicación: el modal es solo URL + secreto opcional.

## Eventos enviados [#events-sent]

| Webhook | Se dispara con                                                                                                  |
| ------- | --------------------------------------------------------------------------------------------------------------- |
| Chat    | Cada mensaje en un chat observado: del cliente, del asistente y de un operador                                  |
| Llamada | El final de una llamada: una única entrega posterior con duración, metadatos y la URL de la grabación si existe |

## Evento de llamada [#call-event]

El webhook de llamadas envía un objeto JSON plano por cada llamada finalizada (sin `result_json` anidado). Campos principales:

| Campo                       | Significado                                                                                                                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type`                | Siempre `post_call`                                                                                                                                                                                 |
| `call_uuid`                 | ID único de la llamada — deduplica por él, la misma llamada puede llegar más de una vez                                                                                                             |
| `externalNumber`            | Teléfono del cliente, el mismo que en el historial de llamadas; `null` si no hubo (p. ej., llamada web)                                                                                             |
| `direction`                 | `inbound`, `outbound` o `null`                                                                                                                                                                      |
| `summary`, `callSuccessful` | Resumen y veredicto de la IA: `success`, `failure` o `unknown`                                                                                                                                      |
| `dynamicVariables`          | Las variables con las que se inició la llamada, devueltas — pasa tu ID de contacto en el CRM o de pedido al iniciar la llamada y léelo aquí. Las variables de sistema de VA (`system__*`) se omiten |

Esquema completo y ejemplo: [api.happ.tools/reference](https://api.happ.tools/reference).

## Verificar las solicitudes [#verifying-requests]

Define un secreto del webhook y cada entrega llevará dos encabezados:

| Encabezado      | Valor                                                                                  |
| --------------- | -------------------------------------------------------------------------------------- |
| `Authorization` | `Basic <secret>`: tu secreto tal cual, no el base64 de `user:password`                 |
| `X-Signature`   | `sha256=<hex>`: HMAC-SHA256 del cuerpo bruto de la solicitud, calculado con tu secreto |

Verifica recalculando el HMAC-SHA256 sobre el cuerpo bruto (antes de parsear el JSON) y comparando en tiempo constante. Si tu plataforma no da acceso al cuerpo bruto, comprueba en su lugar el encabezado `Authorization`. Sin secreto definido, no se envía ninguno de los dos encabezados. El mismo mecanismo que en las [herramientas](/docs/agents/tools) del asistente.

Usa solo HTTPS, responde `200` rápido (procesa de forma asíncrona) y gestiona las entregas duplicadas de forma idempotente.

## Webhooks frente a webhooks de herramientas [#webhooks-vs-tool-webhooks]

|             | Webhooks de integración       | Webhooks de herramientas                |
| ----------- | ----------------------------- | --------------------------------------- |
| Disparador  | Automático ante eventos       | Los llama la IA durante la conversación |
| Dirección   | Happ → tu servidor            | Happ → tu servidor → respuesta → IA     |
| Respuesta   | Confirmación HTTP 200         | JSON que usa el asistente               |
| Caso de uso | Supervisión, registro, avisos | Consultas dinámicas, acciones           |

Para los webhooks que la IA llama durante la conversación, consulta [Herramientas](/docs/agents/tools).

**API:** [api.happ.tools/reference](https://api.happ.tools/reference)

## Siguiente [#next]

* [Herramientas](/docs/agents/tools): webhooks que llama la IA
* [Notificaciones](/docs/integrations/notifications): avisos integrados
* [Integraciones](/docs/integrations): el catálogo completo