Abre Automatizaciones en la barra lateral izquierda y entra a la pestaña Webhooks. La página se describe con precisión: "Callbacks HTTP que se disparan ante eventos de contactos, mensajes o workflows. Configura suscripciones por evento e inspecciona el historial de entregas por fila." Una suscripción es una instrucción permanente: cuando pase algo de este tipo, publícalo en mi servidor. Cada entrega va firmada, se reintenta si falla y queda registrada, y vale la pena entender las tres cosas antes de apuntar ahí un endpoint de producción.
Tres cosas se llaman webhook: esta pestaña es una de ellas
La palabra trabaja de más en IcloneU, y las tres superficies apuntan en direcciones distintas. Equivocarse de dirección es la razón más común por la que alguien termina en la página equivocada.
| Cuál | Dirección | Dónde vive |
|---|---|---|
| Suscripciones de webhook | IcloneU → tu servidor | Esta pestaña. Le das una URL a IcloneU y publica eventos en ella. |
| Webhooks de canal | Meta, Telegram → IcloneU | No es una página que administres. Son registros que guarda el canal para que los mensajes entrantes lleguen a IcloneU. Cuando uno se rompe, dejan de llegar mensajes. |
| El activador de webhook entrante | Lo que sea → un flujo | Un activador dentro del editor de Flujos. Te da una URL secreta a la que un sistema externo publica para iniciar un solo flujo. |
Todo lo que sigue es solo la primera fila. Si los mensajes de tus clientes dejaron de llegar, la guía que buscas es Cuando los mensajes dejan de llegar; si quieres que un sistema externo inicie un flujo, es el activador de webhook entrante de Activadores de flujo.
Crear una suscripción
Haz clic en Nueva suscripción
Arriba a la derecha de la pestaña Webhooks. El botón solo aparece si tu rol en el equipo puede gestionar Herramientas de desarrollador; un rol que solo puede verlas ve la pestaña sin él. El diálogo tiene tres campos, y solo dos le importan a la máquina.
Escribe la URL de destino
URL de destino tiene que ser una URL absoluta http o https; el texto de ejemplo muestra la forma, https://example.com/webhook. Una ruta relativa o un nombre de host suelto dejan el botón de crear deshabilitado en vez de fallar después. La URL tiene que responder directamente: IcloneU no sigue redirecciones, así que una respuesta 301, 302, 307 o 308 cuenta como entrega fallida, también en Enviar prueba. Pon la dirección final; un caso común es una dirección http que redirige a https.
Descríbela
Descripción es texto libre y opcional. La tabla nunca la muestra, pero toda lectura por API sí la devuelve, así que es la nota para ti mismo que sobrevive a un cambio de personal: nombra el sistema del otro lado, como sugiere el texto de ejemplo.
Marca los Tipos de evento
Tipos de evento es una lista con scroll de los doce eventos a los que puedes suscribirte. Hay que marcar al menos uno antes de que Crear se active. Marca solo lo que de verdad vayas a procesar: cada evento de más es otra entrega que tu endpoint tiene que contestar en menos de 15 segundos.
Guarda el secreto de firma
Al crear la suscripción, su secreto de firma se muestra una sola vez, en un diálogo con un botón de copiar y un recordatorio en palabras llanas de para qué sirve: "Guarda este secreto en un lugar seguro. Tu sistema lo usa para confirmar que los eventos que enviamos realmente provienen de IcloneU." Son 64 caracteres hexadecimales. Guárdalo como secreto en tu propio sistema: no vuelve a aparecer, ni en la tabla ni en la API.
AtenciónSi pierdes el secreto no puedes volver a leerlo. La recuperación es Rotar secreto, que acuña uno nuevo e invalida el anterior de inmediato, así que tu receptor deja de verificar hasta que despliegues el valor nuevo.
El diálogo de creación no tiene campo Estado: una suscripción nueva siempre nace activa. El campo aparece cuando vuelves a abrir una suscripción existente con Editar (o con doble clic en su fila), y ahí es donde la pausas o donde regresas una que quedó en Unhealthy.
Los doce eventos
La lista es fija —no puedes definir tu propio evento— y cada nombre lleva el sufijo .v1 para que un cambio de forma futuro pueda salir como .v2 a un lado en vez de romper tu parser. El correo envía eventos como los demás canales —el mensaje, la respuesta del Clon, un contacto creado a partir de él, un flujo que inicie— y también los comentarios de YouTube que IcloneU recoge en su propio horario. Una respuesta del Clon que se retuvo para aprobación o que quedó programada por los tiempos de respuesta envía assistant.reply_generated.v1 cuando se escribe, pero ningún message.sent.v1 cuando sale después. Y el Chat web no envía eventos por los mensajes del visitante ni por las respuestas del Clon: una conversación nueva envía conversation.started.v1, el primer chat de un visitante identificado envía contact.created.v1, y una respuesta que escribe ahí un miembro del equipo o un mensaje enviado por la API envía message.sent.v1.
| Evento | Se dispara cuando |
|---|---|
| message.received.v1 | Llegó un mensaje de un contacto. |
| message.sent.v1 | Se entregó al canal una respuesta del Clon en cuanto se escribió; se entregó una respuesta que un miembro del equipo escribió en una conversación que tomó; o se entregó un mensaje enviado por la API (la llamada respondió delivery_status delivered). La respuesta de un miembro del equipo lleva sent_by: agent y un mensaje de la API lleva sent_by: api; las dos cuentan también en Chat web. Las respuestas retenidas para aprobación o programadas por los tiempos de respuesta, y los mensajes que se envían desde un flujo, una secuencia o una difusión, no lo disparan. |
| conversation.started.v1 | Empezó una conversación nueva de Chat web: en el widget de chat de tu sitio o desde el widget de Reseñas. Los chats de prueba del Playground no lo envían, ni los demás canales. |
| assistant.reply_generated.v1 | Un Clon produjo una respuesta. |
| assistant.handoff_requested.v1 | Una conversación pidió un humano. |
| assistant.handoff_resolved.v1 | Terminó la transferencia a un humano y el control volvió al Clon. |
| contact.created.v1 | Se creó un contacto nuevo. |
| contact.updated.v1 | Cambió un contacto existente. |
| tag.applied.v1 | Se puso una etiqueta a un contacto. |
| tag.removed.v1 | Se quitó una etiqueta a un contacto. |
| custom_field.changed.v1 | Un campo personalizado de un contacto cambió de valor. |
| automation.run.completed.v1 | Se ejecutó hasta su final o hasta su primera espera un flujo iniciado por un mensaje, correo o comentario entrante (o por un clic en un anuncio, un enlace de referencia o un código QR). Su campo status dice completed, o waiting cuando la ejecución se detuvo en una espera o para esperar la respuesta del cliente (el resto de esa ejecución ya no envía nada), y automation_id identifica el flujo. Los flujos que se inician de otra forma —eventos de contacto, fechas, segmentos, webhooks entrantes, eventos de tienda, secuencias— no lo envían. |
No existe un evento conversation.closed, porque las conversaciones nunca se cierran: un contacto que vuelve retoma la conversación que ya existe, así que no hay momento en el cual disparar. Usa assistant.handoff_resolved.v1 si lo que quieres de verdad es "el humano ya terminó". Y webhook.test.v1 —el evento que dispara Enviar prueba— queda fuera de la lista a propósito: se entrega a cualquier suscripción sin importar lo que esté marcado, así que tu receptor tiene que manejarlo aunque no te puedas suscribir a él.
Si prefieres leer la lista desde código en vez de desde una guía, GET /api/public/webhooks/event-types devuelve los dos conjuntos: event_types con los doce y system_event_types con el evento de prueba.
Qué recibe tu endpoint y cómo verificarlo
Cada entrega es un POST HTTP con cuerpo JSON y los mismos cinco encabezados. El cuerpo siempre es el mismo sobre, con el detalle propio del evento anidado bajo data.
| Encabezado | Qué lleva |
|---|---|
| X-IcloneU-Event | El tipo de evento, p. ej. contact.created.v1. |
| X-IcloneU-Delivery-Id | Un GUID del registro de entrega. Cada reintento de la misma entrega lo repite, así que es lo que vuelve idempotente tu manejador; un Reenviar es un registro nuevo y recibe un id nuevo. |
| X-IcloneU-Timestamp | Segundos Unix del momento del envío. Es parte del material firmado, así que no puedes sustituirlo por el tuyo. |
| X-IcloneU-Signature | La prueba. sha256= seguido de un HMAC-SHA256 en hexadecimal minúsculo. |
| User-Agent | IcloneU-Webhook/1.0. |
El sobre: id (un GUID del evento en sí), event (el tipo), account_id, occurred_at (una marca de tiempo ISO-8601) y data. Los nombres de campo van en snake_case.
La firma se calcula sobre la cadena literal {timestamp}.{body}: la marca de tiempo del encabezado, un punto, y luego el cuerpo exactamente como llegó por el cable. Con tu secreto de firma como llave —usado como texto, tal como se muestra, sin decodificarlo de hexadecimal—, HMAC-SHA256, en hexadecimal minúsculo y con el prefijo sha256=. Si tu framework parsea el JSON y tú lo vuelves a serializar para verificar, los bytes serán distintos y todas las firmas se verán mal. Captura el cuerpo crudo antes de que nada lo toque y compara el resultado en tiempo constante.
Responde con cualquier 2xx y la entrega cuenta como exitosa. Cualquier otra cosa —una redirección, un 4xx, un 5xx, un tiempo agotado, una conexión rechazada, un certificado vencido— es un fallo y arranca la escalera de reintentos. IcloneU espera 15 segundos tu respuesta. Los primeros 4 KB del cuerpo de tu respuesta se guardan con la entrega, pero hoy nada en el producto ni en la API te los muestra de vuelta: lo único que puedes leer es el código de estado, en la columna Código del historial de entregas. Guarda tus propios registros del lado receptor; ahí va a estar el motivo.
Reintentos, abandono y la trampa de Unhealthy
Una entrega fallida se reintenta en una escalera que se abre: 1 segundo, 10 segundos, 1 minuto, 10 minutos, 1 hora, 6 horas y 24 horas. Son ocho intentos en total, repartidos en unas 31 horas. Después del octavo la entrega se abandona: nunca se volverá a intentar sola, y solo Reenviar la puede traer de vuelta.
Aparte de cualquier entrega individual, la suscripción lleva la cuenta corrida de entregas fallidas consecutivas. Un éxito —incluido un reintento que por fin pasa— la regresa a cero y sella Última entrega. Cada entrega cuenta una vez, cuando falla su primer intento; sus reintentos no suman. Diez entregas seguidas que fallan, sin ningún éxito entre ellas, cambian el estado de la suscripción a Unhealthy, así que un endpoint caído mientras llegan diez eventos la apaga.
Solo se alimenta una suscripción activa. Una en pausa o en Unhealthy se salta al encolar eventos nuevos y se salta al recoger reintentos pendientes, así que una suscripción en Unhealthy no recibe absolutamente nada, lo que significa que nada puede tener éxito, lo que significa que el contador de fallos nunca se reinicia. Se queda así hasta que una persona la abre con Editar y regresa el Estado a activa. Arregla tu endpoint primero, confírmalo con Enviar prueba y después reactívala. Reactivarla —en la página o por la API— regresa el conteo de Fallos a cero, así que la suscripción empieza limpia; las entregas que ya esperaban un reintento se vuelven a enviar en cuanto está activa.
Los eventos que ocurren mientras una suscripción está en pausa o en Unhealthy no se guardan para después. Simplemente nunca se encolan para esa suscripción, así que no hay una fila esperando cuando la reactives: el hueco en tus datos es permanente. Si la continuidad importa, pausa la ventana más corta que puedas y rellena después desde la API.
Los webhooks también se detienen cuando tu plan se detiene. Mientras la cuenta no tenga un plan activo o de prueba, los eventos nuevos no se envían a ninguna suscripción, y las entregas que ya esperaban se cierran sin enviarse: quedan en el historial como Failed con código 0 y no suman a Fallos. Los eventos que IcloneU procesa en segundo plano, como el correo y las difusiones, todavía pueden aparecer en el historial de entregas como Failed con código 0 mientras el plan está vencido. Tus suscripciones y sus secretos se conservan, y los eventos nuevos vuelven a fluir unos 10 minutos después de renovar. Nada del periodo sin plan se envía después por sí solo.
Del lado del envío, las entregas se recogen cada 5 segundos, hasta 50 por ciclo y con un máximo de 8 en vuelo a la vez. Un receptor que tarda los 15 segundos completos ocupa uno de esos lugares y retrasa el siguiente ciclo para todas las entregas en espera: otra razón para responder 200 de inmediato y hacer el trabajo real desde una cola.
La tabla y las cinco acciones de fila
La tabla lista URL de destino con la insignia de estado a un lado, y luego Eventos (cuántos están marcados), Fallos (los fallos consecutivos), Última entrega y Creado. Selecciona una fila y se activan cinco acciones.
- Editar — vuelve a abrir el diálogo con Estado agregado. Aquí es donde pausas una suscripción en vez de eliminarla, y es el único camino de regreso desde Unhealthy. El doble clic en la fila hace lo mismo.
- Entregas — las últimas 100 entregas, de la más nueva a la más vieja, con Evento, Estado, Código, Intento y Hora, y un botón Reenviar en cada fila. Las entregas que pasan de esas 100 siguen en el historial hasta 30 días y se pueden leer y reenviar por la API.
- Enviar prueba — publica un webhook.test.v1 firmado en la URL en este momento, de forma síncrona, y te dice el estado HTTP que recibió: "Evento de prueba enviado (HTTP {0})." si funcionó, "Falló la entrega de prueba: {0}." si no. Ignora el estado de la suscripción, así que funciona en una fila en pausa o en Unhealthy, que es justo lo que la vuelve la revisión correcta antes de reactivar una. El intento queda en el historial de entregas y nunca se reintenta.
- Rotar secreto — acuña un secreto de firma nuevo y lo muestra una sola vez. La confirmación plantea el riesgo en el orden correcto: "Se generará un nuevo secreto de firma y se mostrará una sola vez. El secreto actual deja de funcionar de inmediato, así que actualiza tu receptor antes de rotarlo."
- Eliminar — quita la suscripción y detiene todos sus eventos. No hay deshacer ni papelera de reciclaje; si solo quieres detener las entregas un rato, pon el Estado en pausa.
En el historial de entregas, Estado muestra OK para un 2xx, Retry mientras siga programado otro intento y Failed cuando se agotaron los intentos. Las tres insignias de estado de las filas de la tabla —Active, Paused, Unhealthy— son la misma historia. Las seis están fijas en el código hoy y se muestran en inglés sin importar el idioma de la interfaz.
Reenviar no repite el intento original. Encola el mismo evento y la misma carga como una entrega nueva, que arranca otra vez en el intento uno con la escalera de reintentos completa por delante, y va firmada con el secreto vigente, no con el que estaba en uso cuando ocurrió el evento.
Hacer todo esto desde código
Cada pantalla de arriba tiene su equivalente en la API bajo /api/public/webhooks, así que una integración puede aprovisionar su propia suscripción al instalarse en vez de pedirle a una persona que le dé clic a esta pestaña. Leer está abierto a cualquier llave; cada escritura pide una llave Full Access, porque una llave que puede crear webhooks puede reenviar en silencio el tráfico de tu cuenta a otro lado.
| Llamada | Nivel que pide |
|---|---|
| Listar suscripciones, abrir una, listar sus entregas, listar los tipos de evento | Cualquier llave, incluida Read Only |
| Crear, actualizar o eliminar una suscripción | Full Access |
| Enviar un evento de prueba, rotar el secreto de firma, reenviar una entrega pasada | Full Access |
La creación devuelve el secreto de firma en la respuesta —la única vez que aparece— y toda lectura posterior lo omite a propósito. La rotación devuelve el nuevo secreto de la misma forma. Los listados de entregas están paginados de verdad: meta.total es el número real de entregas guardadas para esa suscripción, no una estimación, así que puedes paginar hasta el final y saber que llegaste. Una actualización cambia solo los campos que mandas: si omites target_url, event_types, description o status, conserva su valor, y una description vacía la borra. Regresar status a activa reinicia el conteo de fallos, igual que en la página. Los niveles de acceso están en Llaves API públicas.
IcloneU guarda cada entrega 30 días y borra las más viejas en una limpieza diaria, salvo una entrega fallida que todavía espera un reintento. Dentro de esos 30 días, el endpoint de reenvío encuentra cualquier entrega por su id, aunque ya no esté entre las últimas 100 que muestra la lista de Entregas. Si necesitas repetir algo más antiguo, repítelo desde tus propios registros y no desde los nuestros.
Preguntas frecuentes
Sí. Cada suscripción se evalúa por su cuenta, así que un evento que coincide con tres suscripciones produce tres entregas, cada una firmada con su propio secreto. Esa es la forma limpia de mandar el mismo evento a un endpoint de pruebas y a uno de producción.
Sí, si la suscripción sigue activa: cada entrega fallida sigue reintentando unas 31 horas. Pero cada entrega cuyo primer intento falla cuenta para los diez que ponen una suscripción en Unhealthy (sus reintentos no), así que una caída en la que llegan diez eventos la apaga. Los eventos que ocurren mientras está en pausa o en Unhealthy nunca se encolan para ella ni se recuperan cuando regresa; las entregas que ya esperaban un reintento sí se reanudan.
Abre la suscripción con Editar y pon el Estado en pausa. La URL, la lista de eventos y el secreto de firma sobreviven; regresarla a activa reanuda los eventos nuevos. Eliminar es la opción destructiva y se lleva el secreto con ella.
Casi siempre el material firmado. Es {timestamp}.{body} con el cuerpo crudo: no el cuerpo solo, no una copia vuelta a serializar y no el objeto parseado. Confirma que lees la marca de tiempo de X-IcloneU-Timestamp, que comparas contra el valor que sigue a sha256= y que tu hexadecimal está en minúsculas. Usa el secreto como texto, tal como se muestra, para calcular el HMAC: no lo decodifiques de hexadecimal. Enviar prueba te da una entrega firmada cuando la pidas para contrastar.
No, y apuntan en sentidos opuestos. Esta pestaña hace que IcloneU te llame cuando pasa algo. El activador de webhook entrante le da a un sistema externo una URL secreta a la que llamar para iniciar un flujo específico. Ninguno de los dos es el webhook de canal que trae los mensajes de tus clientes a IcloneU.
Última actualización: octubre 6, 2026 · Automatizaciones
