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

# Webhooks

> Haz que Ciarem envíe una solicitud HTTPS a tu servidor en el momento en que cambia un contacto, una conversación o un mensaje.

Un webhook es una solicitud que Ciarem envía **a tu servidor** cuando pasa algo en tu cuenta: se crea un contacto, se asigna una conversación, un cliente escribe. Le das una URL a Ciarem, eliges los eventos que te interesan, y cada evento que coincide llega como un `POST` firmado en segundos.

Usa webhooks cuando quieras reaccionar a los cambios en vez de preguntarle a la [API](https://help.ciarem.ai/es/api-reference/quickstart.md) una y otra vez si hay algo nuevo. Usos típicos:

* Mantener tu propio CRM o data warehouse al día con los contactos de Ciarem.
* Avisar a un equipo en Slack cuando una conversación se asigna o se cierra.
* Iniciar una automatización en tu backend cuando un cliente envía un mensaje.

> [!NOTE]
>
> No necesitas webhooks para usar Ciarem. Son una herramienta para desarrolladores que conectan Ciarem con sus propios sistemas. Necesitas un servidor que pueda recibir solicitudes HTTPS desde internet.

## Antes de empezar

| | |
| - | - |
| **Plan** | Los webhooks son parte del acceso a la API: **Growth**, **Scale** o la **prueba gratuita**. |
| **Quién puede configurarlos** | Los **administradores** de la organización en el panel, o cualquier integración que tenga una [clave de API](https://help.ciarem.ai/es/api-reference/authentication.md). |
| **Tu endpoint** | Una URL **HTTPS** pública que responda solicitudes `POST`. Consulta [qué acepta Ciarem](#requisitos-de-la-url). |

## Configura tu primer endpoint

**En el panel**

**1. Abre Webhooks**

Ve a **Configuración**, luego a **Webhooks**, y haz clic en **Agregar endpoint**.

**2. Ingresa tu URL**

Pega la dirección HTTPS de tu servidor en **URL del endpoint**. Agrega una descripción si quieres recordar para qué es el endpoint.

**3. Elige los eventos**

Deja **Enviar todos los eventos** activado para recibir todo, incluidos los tipos de evento que se agreguen en el futuro, o desactívalo y marca solo los eventos que necesitas. Consulta el [catálogo de eventos](https://help.ciarem.ai/es/webhooks/events.md).

**4. Copia el secreto de firma**

Después de guardar, Ciarem muestra el **secreto de firma** del endpoint. Empieza con `whsec_`. Guárdalo en tu servidor: lo usas para [comprobar que cada solicitud viene de verdad de Ciarem](https://help.ciarem.ai/es/webhooks/signatures.md). Puedes volver a verlo más tarde en la página del endpoint con **Mostrar secreto**.

**5. Envía un evento de prueba**

Abre el endpoint, elige un evento en **Evento de prueba** y haz clic en **Enviar evento de prueba**. Ciarem lo envía de inmediato y te dice qué respondió tu servidor.

**Con la API**

Crea el endpoint:

```bash theme={null}
curl https://api.ciarem.ai/v1/webhook-endpoints \
  -H "Authorization: Bearer oak_TU_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/ciarem",
    "description": "Sync contacts to our CRM",
    "events": ["contact.created", "contact.updated", "contact.deleted"]
  }'
```

La respuesta es el endpoint más su secreto de firma:

```json theme={null}
{
  "id": "whe_…",
  "url": "https://example.com/hooks/ciarem",
  "description": "Sync contacts to our CRM",
  "events": ["contact.created", "contact.deleted", "contact.updated"],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-09T15:04:05.123456Z",
  "updated_at": "2026-10-09T15:04:05.123456Z",
  "secret": "whsec_…"
}
```

> [!WARNING]
>
> La API devuelve `secret` **solo en esta respuesta**. Guárdalo ahora. Un administrador puede leerlo más tarde en el panel (**Configuración → Webhooks →** el endpoint **→ Mostrar secreto**), pero ninguna llamada a la API lo vuelve a devolver.

Luego envía un evento de prueba para confirmar que tu servidor lo recibe:

```bash theme={null}
curl -X POST https://api.ciarem.ai/v1/webhook-endpoints/whe_…/test \
  -H "Authorization: Bearer oak_TU_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "contact.created"}'
```

```json theme={null}
{
  "delivered": true,
  "response_status": 200,
  "error": null,
  "payload": { "id": "evt_test_…", "type": "contact.created", "…": "…" }
}
```

Para recibir todos los tipos de evento, incluidos los que se agreguen después, envía `"events": ["*"]`. El `*` debe ser el único elemento de la lista.

## Qué envía Ciarem

Cada evento es una solicitud `POST` con un cuerpo JSON:

```http theme={null}
POST /hooks/ciarem HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Ciarem-Webhooks/1.0 (+https://ciarem.ai)
Ciarem-Signature: t=1760022245,v1=5f8a…c2e1

{"id":"evt_…","type":"contact.created","api_version":"v1","created_at":"2026-10-09T15:04:05.123456Z","data":{"contact":{"id":"cnt_…","first_name":"Ana","…":"…"}}}
```

| Parte | Qué es |
| - | - |
| `Ciarem-Signature` | La prueba de que la solicitud viene de Ciarem y no fue alterada. [Verifícala](https://help.ciarem.ai/es/webhooks/signatures.md) antes de confiar en el cuerpo. |
| `id` | El id único del evento. El mismo evento siempre lleva el mismo `id`, también cuando se reintenta. Úsalo para [ignorar duplicados](https://help.ciarem.ai/es/webhooks/deliveries.md#duplicados-y-orden). |
| `type` | Qué evento es, por ejemplo `contact.created`. Consulta el [catálogo de eventos](https://help.ciarem.ai/es/webhooks/events.md). |
| `api_version` | Hoy siempre es `v1`. |
| `created_at` | Cuándo ocurrió el evento en Ciarem, en UTC. |
| `data` | Los detalles. Su forma depende de `type`. |

## Qué debe hacer tu servidor

1. **Responde con un estado `2xx` en menos de 10 segundos.** Cualquier `2xx` cuenta como recibido. Todo lo demás, incluida una redirección, un timeout o un error de conexión, cuenta como fallo y se [reintenta](https://help.ciarem.ai/es/webhooks/deliveries.md#reintentos).
2. **Verifica la firma** antes de actuar sobre el cuerpo. Consulta [Verificar firmas](https://help.ciarem.ai/es/webhooks/signatures.md).
3. **Responde primero, trabaja después.** Si procesar un evento toma tiempo, guárdalo en una cola y devuelve `200` de inmediato. Ciarem no lee el cuerpo de tu respuesta.
4. **Espera duplicados y eventos fuera de orden.** El mismo evento puede llegar más de una vez, y dos eventos pueden llegar en un orden distinto al que ocurrieron. Consulta [Duplicados y orden](https://help.ciarem.ai/es/webhooks/deliveries.md#duplicados-y-orden).
5. **Ignora lo que no reconozcas.** Con el tiempo se agregan nuevos tipos de evento y nuevos campos. Responde `200` a los valores de `type` desconocidos y sáltalos, y no rechaces cuerpos con campos adicionales.

## Requisitos de la URL

Ciarem solo envía a URLs que es seguro llamar desde el internet público:

* La URL debe empezar con `https://`. El `http://` sin cifrar se rechaza.
* El host debe resolver a una dirección IP **pública**. `localhost`, los rangos de red privada (como `10.x.x.x` o `192.168.x.x`) y las direcciones link-local se rechazan, tanto al guardar el endpoint como en cada entrega.
* Tu servidor debe presentar un certificado TLS válido para ese nombre de host.
* Las redirecciones **no se siguen**. Un `301` o `302` se registra como una entrega fallida, así que registra la URL final.
* La URL puede tener hasta 2,048 caracteres y puede incluir una ruta, un puerto y una cadena de consulta.

> [!TIP]
>
> Para probar contra un servidor en tu propia computadora, exponlo con un túnel que te dé una dirección HTTPS pública, como ngrok o Cloudflare Tunnel, y registra la URL del túnel.

## Límites

| | |
| - | - |
| Endpoints por organización | 10 |
| Tiempo de respuesta permitido | 10 segundos |
| Reintentos de una entrega fallida | Durante un máximo de 3 días, consulta [Reintentos](https://help.ciarem.ai/es/webhooks/deliveries.md#reintentos) |
| El registro de entregas se conserva | 30 días |
| Longitud de la descripción | 500 caracteres |

## Siguientes pasos

> **[Catálogo de eventos](https://help.ciarem.ai/es/webhooks/events.md)**
>
> Cada tipo de evento y el cuerpo exacto que lleva.

> **[Verificar firmas](https://help.ciarem.ai/es/webhooks/signatures.md)**
>
> Comprueba que una solicitud viene de Ciarem, con código que puedes copiar.

> **[Entregas y reintentos](https://help.ciarem.ai/es/webhooks/deliveries.md)**
>
> Reintentos, el registro de entregas, enviar de nuevo y solución de problemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.