Webhooks: enviar tus eventos de Joinways a tus herramientas

Un grupo hotelero quiere ver cada reserva confirmada en su almacén de datos al minuto, sin exportaciones manuales. Consultar la API cada cinco minutos gasta llamadas y a veces se pierde un cambio.

Un webhook invierte el sentido: es Joinways quien llama a tu dirección HTTPS en cuanto cambia una solicitud, un evento o un presupuesto, con el registro actualizado y una firma que verificar. Hay dos mecanismos: las suscripciones, que escuchan todo el espacio, y la acción « Llamar a un webhook » de una automatización, que solo se dispara cuando su regla lo decide.

Lo que vas a aprender

• Elegir entre una suscripción y la acción de automatización.
• Crear una suscripción y guardar su secreto.
• Verificar la firma de una llamada.
• Entender los reintentos y la desactivación automática.
• Ver y eliminar los webhooks del espacio.

Requisitos previos

• El plan Pro o el periodo de prueba.
• El rol « Propietario » o « Administrador » para crear una suscripción y ver la página « Desarrolladores ».
• Una dirección HTTPS pública que responda rápido. Se rechazan las direcciones locales, los rangos privados y los nombres internos.

1. Elegir el mecanismo adecuado

• Suscripción: registras una dirección una vez y Joinways la llama en cada cambio del tipo elegido, en todo el espacio. Es lo que usa Zapier, y lo que necesitas para copiar tus datos o controlar Make o n8n.
• Acción « Llamar a un webhook »: un paso de automatización que se envía tras el plazo y las condiciones de la regla. Por ejemplo, dos días después del final de una boda de más de 100 invitados.
• Ninguno de los dos: para leer datos bajo demanda, usa una clave API y llama a la API.

2. Crear una suscripción

Una suscripción no se crea desde un formulario de la app. Hay dos vías:

• Zapier: un Zap construido sobre un disparador de Joinways crea la suscripción por ti (consulta Conectar Joinways con Zapier).
• La API: POST /api/v1/webhooks con una clave API, un target_url y la lista event_types.

Hay ocho tipos de eventos disponibles:

• lead.created: llega una solicitud.
• lead.archived: se archiva una solicitud.
• lead.merged: una solicitud duplicada se fusiona en otra (campo merged_into_lead_id).
• event.created: se crea un evento.
• event.status_changed: cambia el estado de un evento (previous_status, new_status).
• event.stage_changed: cambia la etapa de un evento (previous_stage_id, new_stage_id, new_stage_name).
• quote.created: se crea un presupuesto.
• quote.status_changed: cambia el estado de un presupuesto, firma incluida.

La respuesta contiene el secreto de firma (whsec_…), una sola vez. Guárdalo enseguida: sin él no puedes verificar ninguna llamada. Un espacio admite como máximo 25 suscripciones activas.

3. Recibir y verificar una llamada

Cada envío es un POST JSON: event_type, account_id, occurred_at, los campos propios del tipo y data, el registro releído al construir el envío, con la forma que devuelve la API (un elemento de GET /events o de GET /leads, o el objeto quote de GET /quotes/{id}). Los eventos de varios días llevan sus horarios por día en day_hours.

Las cabeceras:

• X-Joinways-Event: el tipo de evento.
• X-Joinways-Delivery: un identificador único, el mismo en todos los reintentos de un envío. Elimina duplicados con este valor.
• X-Joinways-Timestamp: la hora de envío, en segundos Unix.
• X-Joinways-Signature-V2: sha256= seguido de un HMAC-SHA256 de <timestamp>.<cuerpo bruto>, calculado con tu secreto.
• X-Joinways-Signature: la primera versión, un HMAC-SHA256 del cuerpo bruto solo, conservada para los receptores existentes.

Para verificar, vuelve a calcular el HMAC sobre el cuerpo exactamente tal como llegó, antes de cualquier lectura JSON, compáralo con la cabecera y rechaza una marca de tiempo de más de 5 minutos para bloquear repeticiones. Un cuerpo reformateado por tu framework nunca coincidirá.

Consejo: responde 200 en cuanto recibas la llamada y procesa la carga en segundo plano. Un endpoint que trabaja antes de responder acaba fallando y luego desactivado.

4. Reintentos y desactivación automática

• Una llamada sin respuesta a los 10 segundos cuenta como fallo. Las redirecciones no se siguen.
• Cada envío se intenta 3 veces seguidas. Si falla por un error de red, un tiempo agotado, un 5xx, 408 o 429, se reintenta a los 10 minutos, 30 minutos, 2 horas, 6 horas y 24 horas, con el mismo X-Joinways-Delivery.
• Otra respuesta 4xx no se reintenta. Una respuesta 410 elimina la suscripción: así indica Zapier que un Zap se ha desactivado.
• Tras 10 envíos fallidos seguidos, la suscripción pasa a « Desactivado ».
• Un webhook que falla nunca bloquea la acción en Joinways.

5. La acción « Llamar a un webhook » de una automatización

En una automatización, la acción « Llamar a un webhook » envía el registro seleccionado a la dirección indicada, tras el plazo y las condiciones de la regla. La cabecera X-Joinways-Event vale entonces workflow.action, lo que permite a un mismo endpoint distinguir las dos fuentes.

El secreto es opcional. Si se indica, la llamada lleva la cabecera X-Joinways-Signature, calculada sobre el cuerpo bruto. Un error de red, 5xx, 408 o 429 se reintenta; otra respuesta 4xx o una redirección se registra como omitida en el historial de la automatización.

6. Ver y eliminar los webhooks

Abre « Configuración » > « Desarrolladores », pestaña « Webhooks ». El contador de la pestaña da el número total. La lista reúne todos los puntos de salida del espacio:

• las suscripciones, con la fuente « Zapier » o « API », la dirección, los eventos escuchados, el estado « Activo » o « Desactivado » y la fecha de creación;
• los webhooks de las automatizaciones, con la fuente « Automatización · » seguida del nombre de la regla y el enlace « Editar en la automatización ».

Para eliminar una suscripción, haz clic en el icono de papelera. La ventana « ¿Eliminar este webhook? » recuerda la dirección y los eventos afectados; la eliminación es definitiva. Una suscripción desactivada no se reactiva: vuelve a crearla.

Ejemplo: las reservas de un grupo en su almacén de datos

Un grupo de tres hoteles suscribe un endpoint a event.status_changed y event.stage_changed. Su receptor verifica la firma V2, responde 200 al momento y escribe la fila indexada por el identificador del evento: un reintento actualiza la fila en lugar de duplicarla. El día que el endpoint se cae, Joinways reintenta durante unas treinta horas; si sigue sin responder diez veces seguidas, la suscripción aparece « Desactivado » en la pestaña « Webhooks ».

Solución de problemas

No llega nada

Causa: la suscripción está desactivada o no escucha el tipo que pruebas. Solución: comprueba su estado y sus eventos en la pestaña « Webhooks » y vuelve a crearla si hace falta.

La firma nunca coincide

Causa: la huella se calcula sobre un cuerpo reserializado, o la V2 se calcula sin la marca de tiempo. Solución: captura el cuerpo bruto antes de cualquier lectura y calcula la V2 sobre <timestamp>.<cuerpo bruto>.

La dirección se rechaza al crearla

Causa: no es HTTPS pública, o apunta a un host privado o interno. Solución: expón una dirección pública; en desarrollo local, usa un túnel.

La creación responde 422 quota_exceeded

Causa: el espacio ya tiene 25 suscripciones activas. Solución: elimina las que ya no uses.

He perdido el secreto

Causa: solo se muestra al crearla. Solución: elimina la suscripción y crea una nueva.

Preguntas frecuentes

¿Puede llegar dos veces el mismo cambio?

Sí, tras un reintento. Elimina duplicados con X-Joinways-Delivery y haz que tu proceso sea idempotente.

¿Pueden varias direcciones escuchar el mismo evento?

Sí. Cada suscripción activa que escucha ese tipo recibe el envío.

¿Está garantizado el envío?

Se reintenta durante unas 33 horas. Después ya no se repite: usa la API como fuente de verdad para conciliar.

¿Puedo crear una suscripción desde la app?

No. Las suscripciones se crean con Zapier o con la API; la pestaña « Webhooks » las lista y las elimina. La acción de una automatización se configura por completo en la automatización.

Ver también

• API REST: crear y gestionar tus claves
• Conectar Joinways con Zapier
• Disparadores, condiciones y acciones: la referencia
• Planes, precios y suscripción