Iniciar un flujo por webhook

El disparador Webhook le da a un flujo su propia URL. Cualquier plataforma que sepa enviar un webhook — tu tienda, un formulario, un CRM, una plataforma de cursos — llama a esa URL con sus datos, en su formato, y el flujo empieza. Cada campo de lo que llegó se puede usar en los mensajes, las plantillas, las condiciones y los campos del contacto.

La diferencia con el disparador API: allí tu sistema llama a Joinotify con una clave y en el formato de Joinotify. Aquí no hay clave ni formato que seguir — pegas una URL en un ajuste de la plataforma y eliges en el editor de dónde viene cada dato.

Preparar el flujo

1. En el editor, añade un disparador y elige Webhook. La URL aparece enseguida, antes de publicar — es la que pegas en la plataforma.
2. En Plataforma, elige WordPress / WooCommerce o Cualquier plataforma.
3. Haz clic en Esperar evento y envía una prueba desde la plataforma (o pega un ejemplo en Pegar JSON). Lo que llegue se convierte en un árbol: desde entonces eliges los campos haciendo clic en vez de escribir rutas.
4. En Contacto, indica dónde está el teléfono — y, si quieres, el nombre y el correo.
5. Conecta el disparador al primer paso, publica y activa el flujo.

La URL tiene la forma https://api.joinotify.com/hooks/whk_… y es la contraseña del disparador: quien tenga la URL puede iniciar el flujo. Si se filtra, Generar una URL nueva cambia la dirección — con la opción de dejar la antigua funcionando 24 horas, para dar tiempo a pegar la nueva.

WooCommerce

1. En WordPress, abre WooCommerce → Ajustes → Avanzado → Webhooks y haz clic en Añadir webhook.
2. Estado: Activo. Tema: Pedido creado — o Pedido actualizado, para seguir el pago y el envío.
3. URL de entrega: la URL del disparador.
4. Secreto: en el disparador, haz clic en Activar la firma de WooCommerce y pega aquí el secreto generado.
5. Guarda. Con Esperar evento activo, haz un pedido de prueba en la tienda para capturar un ejemplo.

Con WooCommerce elegido como plataforma y nada más indicado, el contacto sale del bloque de facturación del pedido: billing.phone, billing.first_name, billing.last_name y billing.email. Un teléfono sin código de país, como (11) 98765-4321, se lee como del país elegido en el disparador (Brasil, por defecto).

La prueba que WooCommerce envía al guardar el webhook (webhook_id=…) se responde sin convertirse en evento.

Un webhook, varios momentos

El tema Pedido actualizado se dispara con cada cambio del pedido. Usa el Filtro del disparador para empezar solo en lo que importa — status igual a processing, por ejemplo — y deja que el mismo pedido con el mismo estado cuente una sola vez (es lo predeterminado, mira Eventos repetidos).

Lo que la plataforma puede enviar

• JSON (application/json) — un objeto; una lista llega como items.
• Formulario (application/x-www-form-urlencoded), incluidos los campos anidados como los escribe PHP: cliente[telefono]=… pasa a ser cliente.telefono.
• Texto, que llega como text.
• La query string de la URL queda en $query, y los encabezados de la plataforma (como X-WC-Webhook-Topic) en $headers — nunca los que autentican.

El cuerpo puede tener hasta 256 kB. Se aceptan POST, PUT y PATCH; un GET a la URL responde 200, para las plataformas que prueban la dirección antes de guardarla.

Firma

Además de la URL, la plataforma puede demostrar que fue ella quien envió. En el disparador, en Firma:

Tipo	Lo que comprueba Joinotify
Solo la URL	Nada más que la dirección (predeterminado)
WooCommerce	X-WC-Webhook-Signature: HMAC-SHA256 del cuerpo, en Base64, con el secreto del webhook
HMAC-SHA256	El encabezado que elijas, en hex o Base64, con prefijo opcional (sha256=)
Encabezado fijo	El encabezado que elijas tiene exactamente el valor acordado

La firma se comprueba sobre los bytes que llegaron, antes de leer el cuerpo. Una llamada con la firma equivocada recibe 401 y no se convierte en evento.

Respuestas

La plataforma solo recibe un error cuando la llamada está mal:

Estado	Cuándo
202	El evento se aceptó — { "ok": true, "event_id": "…" }
404	La URL no existe (o se cambió y terminó el plazo de la antigua)
401	La firma no coincide
400	El JSON no es válido
413	El cuerpo pasa de 256 kB
415	Un formato que Joinotify no lee (multipart/form-data)
429	Demasiadas llamadas — hasta 20 por segundo por URL y 60 por cuenta

Todo lo demás — flujo en pausa, cuenta sin acceso, pedido sin teléfono, evento repetido — es 202 y queda registrado en Eventos recibidos. Es a propósito: una plataforma que recibe errores reintenta y, tras algunos fallos, desactiva el webhook, y nadie se entera de por qué.

Eventos recibidos

En el editor, Eventos recibidos lista cada llamada y lo que pasó con ella:

Estado	Qué significa
Inició el flujo	Una ejecución empezó para el contacto
Filtrado	El evento no pasó el filtro del disparador
Repetido	El mismo evento ya había llegado
Sin teléfono	Ningún teléfono válido en la ruta elegida
Contacto desconocido	El disparador está configurado para no crear contactos, y el teléfono no es de ninguno
Flujo inactivo	El flujo es un borrador o está en pausa
Disparador no publicado	La versión publicada no tiene este disparador
Disparador sin paso siguiente	El contacto se actualizó, pero no se envió nada
Dentro del intervalo	Llegó dentro del intervalo mínimo por contacto
Entregado a quien esperaba	Una ejecución en Esperar evento siguió con él
Cuenta bloqueada	La cuenta no tiene acceso al envío

El detalle de cada evento muestra los datos (con CPF, CNPJ y tarjetas enmascarados hasta que lo pidas), los encabezados y la ejecución que inició, y tiene Ejecutar de nuevo. Los datos de un evento se guardan 30 días, o el plazo de retención de mensajes de tu plan, si es menor. Después solo queda su estado en el registro. En la lista de flujos, un flujo cuyo webhook tuvo tres o más eventos sin resultado en las últimas 24 horas muestra un aviso.

Eventos repetidos

Opción	Cuenta como el mismo evento
Automático — WooCommerce	El mismo pedido con el mismo estado, durante 30 días: editar el pedido no lo confirma otra vez
Automático — otras	Un encabezado de idempotencia (Idempotency-Key, X-Webhook-Id, X-Event-Id, X-Delivery-Id), durante 24 horas; sin él, el mismo cuerpo en 5 minutos
Por un campo	El mismo valor en el campo elegido, durante 24 horas
Por un encabezado	El mismo valor en el encabezado elegido, durante 24 horas
Nunca	Todo evento inicia el flujo

Un evento filtrado no cuenta como visto: el siguiente que pase el filtro empieza normalmente.

Con las demás automatizaciones del contacto

Por defecto, una ejecución iniciada por webhook se ejecuta a la vez que lo que el contacto ya tiene en curso: un pedido no interrumpe la encuesta ni la atención automática que la persona está respondiendo. Cuando el contacto escribe, la respuesta va a la ejecución que espera texto — una pregunta, un Esperar respuesta —, no a una plantilla que espera el toque de un botón.

En el disparador puedes cambiar a Reemplazar solo la anterior de este flujo o Reemplazar cualquier automatización en curso (como los disparadores de conversación), y definir un intervalo mínimo por contacto.

Guardar en el contacto y línea de tiempo

• Guardar en el contacto copia campos del evento a los campos del contacto antes de que empiece el flujo — el valor del último pedido, el documento, la fecha de compra. Luego sirven para segmentar campañas y en otros flujos. El nombre y el correo que envía la plataforma solo completan lo que esté vacío.
• Línea de tiempo escribe una línea en el historial del contacto, que el equipo ve en la bandeja de entrada: Pedido {{trigger.number}} — {{trigger.total:money}}.

Esperar otro evento

El paso Esperar evento detiene una ejecución hasta que un disparador webhook — de este flujo o de otro — reciba un evento con el mismo valor en un campo. Es lo que hace que una recuperación de carrito se detenga cuando el pedido se paga:

1. Un flujo empieza con el evento de carrito abandonado y envía el primer recordatorio.
2. Esperar evento: el disparador del pedido pagado, el valor {{trigger.cart_token}} de esta ejecución, la ruta cart_token en el evento esperado, hasta 1 día.
3. Por la salida Llegó, da las gracias; por No llegó, envía el segundo recordatorio.

El evento que llegó queda en {{flow.<nombre>.…}}, si le das un nombre en el paso.

Probar

Probar, en el editor, puede llevar el ejemplo capturado: la ejecución empieza por el disparador webhook en tu WhatsApp, con las variables completadas como estarían para el cliente.

Siguiente: Variables y datos en los flujos.