Webhooks

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 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.

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.
Tu endpoint	Una URL HTTPS pública que responda solicitudes `POST`. Consulta qué acepta Ciarem.

Configura tu primer endpoint

En el panel
Con la API

Abre Webhooks

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

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.

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.

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. Puedes volver a verlo más tarde en la página del endpoint con Mostrar secreto.

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.

Crea el endpoint:

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:

{
  "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_…"
}

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:

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"}'

{
  "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:

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 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.
`type`	Qué evento es, por ejemplo `contact.created`. Consulta el catálogo de eventos.
`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

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.
Verifica la firma antes de actuar sobre el cuerpo. Consulta Verificar firmas.
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.
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.
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.

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
El registro de entregas se conserva	30 días
Longitud de la descripción	500 caracteres

Siguientes pasos

Catálogo de eventos

Cada tipo de evento y el cuerpo exacto que lleva.

Verificar firmas

Comprueba que una solicitud viene de Ciarem, con código que puedes copiar.

Entregas y reintentos

Reintentos, el registro de entregas, enviar de nuevo y solución de problemas.

Primeros pasos

Canales

Tu agente de IA

Usando Ciarem

Integraciones

App móvil

Facturación

API para desarrolladores

Antes de empezar

Configura tu primer endpoint

Qué envía Ciarem

Qué debe hacer tu servidor

Requisitos de la URL

Límites

Siguientes pasos

Catálogo de eventos

Verificar firmas

Entregas y reintentos

​Antes de empezar

​Configura tu primer endpoint

​Qué envía Ciarem

​Qué debe hacer tu servidor

​Requisitos de la URL

​Límites

​Siguientes pasos

Catálogo de eventos

Verificar firmas

Entregas y reintentos

Antes de empezar

Configura tu primer endpoint

Qué envía Ciarem

Qué debe hacer tu servidor

Requisitos de la URL

Límites

Siguientes pasos