Configurar webhooks

Con una clave API es otro programa el que recoge sus datos cuando los necesita. Con un webhook es al revés: nosotros enviamos un mensaje a una dirección suya en cuanto ocurre algo.

Eso ahorra esperas. Un pedido que entra a las ocho y cuarto está en su contabilidad a las ocho y cuarto — y no en la siguiente ronda, una hora después.

Para qué lo usan nuestros clientes:

• cada venta directamente en la contabilidad o en una base de datos propia;
• una pequeña pantalla en la entrada que muestra quién acaba de entrar;
• un mensaje en un chat de grupo en cuanto una visita guiada se agota;
• un correo o un sms propio al comprador, además del nuestro.

Este artículo es la guía de la pantalla, paso a paso. Si primero quiere saber qué es un webhook y si lo necesita, lea Webhooks.

Conviene saberlo: los webhooks forman parte del mismo plan que la API. En un plan menor Acceso API no aparece en su menú; si aun así llega a la pantalla, verá una explicación y un botón Ir a la suscripción.

Dónde ir

Abra en el menú de la izquierda Ajustes → Acceso API y haga clic arriba en la pestaña Webhooks. Solo el rol Propietario ve esta pantalla.

Verá tres bloques: Nosotros le avisamos (explicación), Nuevo destino (el formulario) y Destinos (lo que ya existe).

Qué necesita

Una sola cosa, y debe existir antes de empezar: una dirección en su propio servidor capaz de recibir mensajes. Eso es un poco de programación por su parte — su desarrollador o su programa de contabilidad entenderá lo que quiere decir con "un endpoint para webhooks".

Tres requisitos:

1. Debe ser https. Una dirección http normal la rechazamos: por esa línea viajan datos de compradores.
2. Debe ser accesible desde fuera. Una dirección dentro de su propia red de oficina (algo con 192.168. o 10.) no podemos alcanzarla, y también la rechazamos.
3. Debe responder rápido. Esperamos diez segundos. Si el procesamiento tarda más, haga que su servidor diga "ok" de inmediato y trabaje después.

Añadir un destino

Paso 1. Escriba la dirección. En el primer campo (https://...), la dirección completa a la que podemos enviar, por ejemplo https://contabilidad.miempresa.es/webhooks/entradas.

Paso 2. Indique para qué es. El segundo campo (¿Para qué es?) no es obligatorio, pero resulta práctico. "Nuestra contabilidad", "pantalla en la caja". Cuando tenga tres, sabrá cuál es cuál.

Paso 3. Marque sobre qué podemos avisarle. La lista está bajo ¿Sobre qué quiere que le avisemos?. Esta es la elección más importante. Marque solo lo que realmente procesa: cada mensaje que no usa es trabajo para su servidor y ruido en su registro. Al menos una casilla debe estar marcada; un destino sin mensajes nunca recibiría nada.

Mensaje	Cuándo sale
Pedido creado	Ha nacido un pedido (un carrito no cuenta).
Pedido pagado	El dinero ha llegado.
Pedido cancelado	El pedido se ha cancelado o ha caducado.
Pedido reembolsado	Ha habido un reembolso total o parcial.
Entrada emitida	Se ha emitido una entrada.
Entrada escaneada	Ha habido un escaneo en la entrada — también si fue rechazado.
Entrada anulada	Una entrada se ha anulado o reembolsado.
Franja horaria agotada	Una franja horaria está llena.
Franja horaria libre de nuevo	Vuelve a haber sitio en una franja llena.
Vale regalo emitido	Se ha vendido una tarjeta regalo.
Vale regalo canjeado	Se ha descontado un importe de una tarjeta regalo.
Pase emitido	Se ha creado un pase anual.
Sesión de caja cerrada	Un cajón de caja se ha contado y cerrado.
Factura emitida	Se ha creado una factura o un abono para un comprador.

Paso 4 (opcional). Destino de prueba. Si la dirección apunta a un entorno de pruebas, marque Destino de prueba (solo recibe eventos de prueba). Más detalles en "Un destino de prueba", más abajo.

Paso 5. Haga clic en Añadir destino.

Puede tener hasta veinte destinos. Si ya tiene veinte, elimine uno primero.

El secreto solo lo ve una vez

Justo después aparece un secreto: una larga cadena que empieza por whsec_.

Cópielo ahora y páselo a quien construya la conexión. Si actualiza la página o cambia de pestaña, habrá desaparecido.

Con ese secreto firmamos cada mensaje que enviamos a su dirección. Su servidor puede comprobar así que el mensaje viene realmente de nosotros y no de alguien que captó su dirección en alguna parte. No es un lujo: sin esa comprobación su endpoint es una puerta abierta por la que cualquiera puede colar pedidos.

¿Ha perdido el secreto? Haga clic en Nuevo secreto. Recibe uno nuevo al instante y el antiguo deja de funcionar desde ese momento — no olvide, por tanto, reemplazarlo también al otro lado.

Para quien construya la conexión, el portal para desarrolladores explica exactamente cómo recalcular esa firma, con ejemplos en PHP, JavaScript y Python. A través de la API también puede pedir un mensaje de ejemplo firmado para probar su propio código, sin tener que hacer antes una venta.

Probar sin venta

Haga clic junto a un destino en Mensaje de prueba. Enviamos entonces un solo mensaje del tipo test.ping — sin datos reales, solo una señal.

Debajo se abre enseguida el registro de mensajes, para que vea lo que respondió su servidor. Si pone Entregado, funciona. Si pone un código de error, sabe dónde mirar. Un mensaje de prueba también sale hacia un destino desactivado.

El registro de mensajes

Haga clic junto a un destino en Mensajes. Verá los últimos cincuenta mensajes y, por cada uno:

• de qué tipo era y cuándo salió;
• lo que devolvió su servidor (el número es el estado http; 200 significa "ok");
• cuántas veces lo hemos intentado;
• cómo está: Entregado, En camino (aún lo estamos intentando) o No entregado.

Si un mensaje no ha llegado, puede volver a ofrecerlo con Intentarlo de nuevo. Práctico después de haber resuelto una avería por su parte.

Los mensajes se conservan treinta días. Después se limpian: el registro sirve para encontrar un problema, no como archivo.

Qué pasa si su servidor no responde

No nos rendimos enseguida. Si un mensaje no llega, lo intentamos seis veces más, con intervalos cada vez más largos: al cabo de un minuto, cinco minutos, media hora, dos horas, doce horas y un día. En total, bastante más de un día y medio.

Si aun así no funciona:

• el destino recibe la marca No llega;
• recibe un correo. Va al Correo de contacto de su organización o, si está vacío, al Correo de facturación (ambos en Ajustes → Organización, pestaña Contacto);
• el destino sigue activo. Los eventos posteriores se ofrecen de nuevo, y en cuanto llegue algo la marca desaparece.

Recibe como mucho uno de esos correos al día por destino. Un servidor caído todo un fin de semana no produce, por tanto, cien correos.

Un destino de prueba

Marque Destino de prueba al crearlo cuando la dirección apunte a un entorno de pruebas. Un destino así solo recibe eventos de prueba — lo que ocurre con los pedidos de prueba de una clave de prueba — y nunca ventas reales. En la lista lleva la marca Prueba. A la inversa, un destino normal nunca recibe nada de un pedido de prueba.

Esa separación es estricta, y a propósito: un servidor de pruebas que procesa por error un pedido real envía una confirmación a un comprador real.

Desactivar o eliminar

Desactivar detiene las entregas pero conserva el destino, con su secreto y su registro; lleva la marca Desactivado. Práctico durante un mantenimiento por su parte. Haga clic de nuevo en Activar y vuelve a funcionar.

Eliminar quita el destino y su registro. No se puede deshacer; un destino nuevo recibe un secreto nuevo.

Hay un tercer caso: si su servidor responde alguna vez con el código 410, desactivamos el destino nosotros mismos. Ese código significa literalmente "esta dirección ya no existe", y seguir llamando sería descortés. Lo mismo ocurre cuando la dirección pasa a apuntar a una red interna. Haga clic en Activar en cuanto esté resuelto.

Tres consejos para quien construya la conexión

1. Responda primero, procese después. Diga "ok" de inmediato y haga el trabajo real en segundo plano. De lo contrario choca con nuestros diez segundos.
2. Procese de forma idempotente. Cada mensaje lleva su propio número (la Idempotency-Key). Si el mismo número llega dos veces, no haga nada. Nosotros reintentamos ante la duda, y una reserva duplicada es peor que una línea de registro duplicada.
3. No cuente con el orden. Dos mensajes pueden adelantarse cuando el primero se repite. Fíjese en la hora del mensaje y en su contenido, no en el orden de llegada.

Para seguir leyendo

• Webhooks — qué es un webhook y cuándo lo necesita, sin términos técnicos.
• Crear una clave API — la otra pestaña de esta pantalla.
• El portal para desarrolladores — para quien construya la conexión.