Webhooks: enviar tus eventos de Joinways a tus herramientas

Un webhook es Joinways llamándote a ti en vez de tú preguntando a Joinways. En cuanto algo cambia en tu espacio, una petición HTTPS llega a una dirección tuya con el registro modificado. Así alimentas un almacén de datos, un canal de Slack propio, una herramienta contable o cualquier cosa que deba reaccionar sin que nadie vuelva a teclear.

Hay dos mecanismos distintos con el mismo nombre, y saber cuál necesitas ahorra una tarde. Este artículo cubre ambos.

Qué plan necesitas

Ambas vías son funciones Pro. La sección Desarrolladores y la API que gestiona las suscripciones requieren Pro, igual que las automatizaciones.

Los dos tipos de webhook

• Suscripciones: registras una dirección una vez y Joinways la llama cada vez que cambia un registro que coincide, en cualquier parte del espacio. Es lo que usa Zapier y lo que quieres para una integración general.
• La acción de automatización: un paso dentro de una regla, disparado solo para los eventos que esa regla retiene, tras su retraso y sus condiciones. Es lo que quieres cuando la llamada debe llevar tu propia regla de negocio.

Las suscripciones responden a adónde van mis datos; la acción de automatización responde a cuándo exactamente debe salir. Pueden convivir en el mismo endpoint, y la cabecera te dice quién llama.

Las suscripciones

A qué puedes suscribirte

Cuatro tipos de eventos, y esta es la lista completa:

• lead.created, cuando llega una nueva solicitud a la Bandeja.
• event.created, cuando se crea un evento.
• event.status_changed, cuando un evento pasa entre Opción, Confirmado, Perdido o Cancelado.
• quote.status_changed, cuando un presupuesto cambia de estado, firma incluida.

Una suscripción puede escuchar varios. Los eventos llegan con la misma forma que devuelve la API en GET /api/v1/events: el mismo código de lectura sirve para ambos.

Crear una

Dos vías, y ninguna es un formulario en la app.

• Con Zapier: crea un Zap sobre un disparador de Joinways y la suscripción se crea sola.
• Llamando tú mismo a POST /api/v1/webhooks, con tu dirección de destino y los tipos de eventos que quieras.

La dirección debe ser HTTPS pública. Las direcciones locales, los rangos privados y los nombres internos se rechazan, así que una prueba en local necesita un túnel con una dirección pública real.

La creación devuelve un secreto de firma, una vez y solo una. Guárdalo enseguida: Joinways no vuelve a mostrarlo, y sin él no puedes verificar ninguna llamada.

Verlas y eliminarlas

Configuración y luego Desarrolladores lista todas las suscripciones del espacio, con su dirección, los eventos que escuchan, si están activas o desactivadas y su fecha de creación. Eliminar una detiene los envíos de inmediato y no se puede deshacer.

Verificar una llamada

Cada envío lleva una cabecera X-Joinways-Signature, con la forma sha256 seguido de una huella hexadecimal. Esa huella es un HMAC-SHA256 del cuerpo bruto de la petición, calculado con tu secreto.

Para comprobarla, calcula el mismo HMAC sobre el cuerpo exactamente tal como se recibió, antes de cualquier lectura o reformateo JSON, y compara ambos. Un cuerpo que tu framework ha vuelto a serializar no coincidirá: es la causa más frecuente de una verificación que falla con una llamada perfectamente válida.

Rechaza todo lo que no coincida, y trata el secreto como una credencial: quien lo tenga puede falsificar una llamada que parezca nuestra.

Envío, reintentos y desactivación automática

• Cada envío se intenta hasta tres veces, con una pausa corta entre intentos.
• Una llamada sin respuesta a los diez segundos se considera fallida. Responde rápido con un 2xx y trabaja después.
• Tras diez fallos consecutivos, una suscripción se desactiva automáticamente, en vez de machacar indefinidamente una dirección muerta.
• Un webhook fallido nunca bloquea la acción dentro de Joinways. Una reserva se confirma aunque tu endpoint esté caído.

💡 Responde 200 en cuanto tengas la carga y procésala en segundo plano. Los endpoints que trabajan antes de responder son los que acaban desactivados.

La acción de automatización

Dentro de una automatización, Llamar a un webhook envía el evento retenido a la dirección que indiques, tras el retraso y las condiciones de la regla. La llamada lleva una cabecera que la identifica como procedente de una acción de automatización, así que un endpoint que también recibe suscripciones puede distinguirlas.

El secreto de firma es opcional aquí: déjalo vacío para un envío sin firmar, o pon uno y obtén la misma cabecera de firma que una suscripción. Se aplica la misma regla de HTTPS público.

Los fallos se comportan distinto que en las suscripciones: un error de red o de servidor por tu parte se reintenta; un rechazo como una dirección errónea se registra como omitido y no se reintenta, porque un endpoint mal configurado no se arregla solo.

Cuál elegir

• Replicar tus datos en algún sitio, o gobernar Zapier, Make o n8n: una suscripción.
• Llamar a algo dos días después de terminar un evento, solo para bodas de más de 100 personas: la acción de automatización, donde viven el retraso y las condiciones.
• Leer datos a demanda en vez de recibirlos: ninguno. Usa una clave API y llama a la API.

Buenas prácticas

• Verifica la firma en cada llamada, sin excepción. Un endpoint sin verificar es un canal de escritura público hacia tus sistemas.
• Haz tu manejador idempotente: un reintento puede entregar dos veces el mismo cambio, y no debe crear dos filas.
• Suscríbete solo a lo que uses. Menos tipos de eventos son menos llamadas y un registro más legible.
• Revisa la lista de Desarrolladores tras un despliegue tuyo: una suscripción desactivada en silencio es la razón clásica de un flujo que se corta.

Resolución de problemas

No llega nada

Causa: la suscripción se desactivó tras fallos repetidos, o no escucha el tipo de evento que estás probando. Solución: abre Configuración y luego Desarrolladores, comprueba su estado y sus eventos, y recréala si hace falta.

La firma nunca coincide

Causa: calculas la huella sobre un cuerpo reserializado y no sobre el bruto. Solución: captura el cuerpo tal como llega, antes de leerlo, y calcula sobre él.

La dirección se rechaza al crearla

Causa: no es HTTPS pública, o apunta a un host privado o interno. Solución: expone una dirección pública real, con un túnel para el desarrollo local.

He perdido el secreto

Causa: solo se muestra una vez, al crearla. Solución: elimina la suscripción y crea otra, que te da un secreto nuevo.

Ejemplo concreto

Un grupo quiere cada reserva confirmada en su propia base de reporting al minuto. Suscribe un endpoint a event.status_changed, verifica la firma y escribe la fila indexada por el identificador del evento, para que un reintento actualice en vez de duplicar. Ya nadie exporta a mano, y un endpoint mudo diez veces seguidas aparece desactivado en Desarrolladores en lugar de como datos que faltan en silencio.

Preguntas frecuentes

¿Puedo crear un webhook desde la app?

Las suscripciones se crean con Zapier o la API; la página Desarrolladores las lista y las elimina. La acción de webhook de una automatización se configura entera en el constructor.

¿Qué eventos existen?

Cuatro: una solicitud creada, un evento creado, un estado de evento cambiado, un estado de presupuesto cambiado.

¿Está garantizada la entrega?

Se intenta tres veces. Más allá, el cambio no se reproduce: considera la API tu fuente de verdad para una reconciliación.

¿Pueden varios endpoints escuchar el mismo evento?

Sí. Cada suscripción activa que coincida con el tipo de evento lo recibe.

¿Un webhook fallido rompe algo en Joinways?

No. El envío ocurre fuera de la acción: nada en la app espera a tu endpoint.

Ver también

• Las claves API
• Disparadores, condiciones y acciones: la referencia
• Planes y tarifas