¿Qué es un webhook?

Jeff Lindsay describió los webhooks en mayo de 2007 como llamadas de retorno definidas por el usuario y hechas con HTTP POST. El usuario indica una URL y la aplicación envía allí un mensaje cuando pasa algo. La especificación Standard Webhooks los llama hoy el nombre habitual de las llamadas de retorno HTTP con las que los servicios se avisan unos a otros de sus eventos.

La diferencia con una API corriente está en la dirección. Con una API, el programa propio pregunta si hay algo nuevo: eso es pull. Con un webhook, el otro servicio avisa por su cuenta en cuanto hay algo nuevo: eso es push. Quien pregunta cada cinco minutos envía muchas peticiones sin resultado y, en el peor caso, se entera de un evento cinco minutos tarde.

Los webhooks complementan las API, no las sustituyen. A menudo el webhook solo trae el aviso de que algo ha cambiado, y el receptor consulta los detalles después por la API.

El proceso tiene tres pasos. Primero, el receptor prepara una dirección capaz de recibir peticiones, el endpoint, y la registra en el servicio emisor junto con los eventos que le interesan. Cuando ocurre uno de ellos, el servicio envía una petición HTTP POST a esa dirección, casi siempre con los datos en formato JSON. El receptor confirma la llegada con un código de estado de la serie 2xx.

Un ejemplo del email marketing: Mailchimp puede avisar por webhook cuando alguien se da de alta o de baja, cambia su dirección de correo o cuando se ha enviado una campaña. Así un CRM puede actualizar el estado de un contacto al momento, sin cotejar la lista cada cierto tiempo.

Cada proveedor decide dos cosas. La primera es el tiempo de espera. GitHub espera una respuesta 2xx en diez segundos; si no llega, corta la conexión y da la entrega por fallida. La segunda son los reintentos. GitHub no vuelve a entregar de forma automática los envíos fallidos. Stripe, en cambio, lo reintenta en modo real durante un máximo de tres días, con intervalos que crecen de forma exponencial. Por eso el receptor tiene que leer en la documentación de cada servicio qué se pierde si su servidor no responde.

Los webhooks conectan herramientas sin que nadie pase datos a mano. Un pedido nuevo en la tienda puede generar una factura, un registro en el CRM y un correo de seguimiento. Muchos flujos de marketing automation se basan en eventos así.

Como el endpoint es accesible desde internet, cualquiera puede llamarlo. Por eso muchos proveedores firman sus webhooks. GitHub envía en la cabecera X-Hub-Signature-256 un hash HMAC calculado con la clave secreta del webhook y el contenido del mensaje. HMAC es un mecanismo de autenticación de mensajes con funciones hash criptográficas, descrito en el RFC 2104 de febrero de 1997. El receptor calcula el mismo hash y compara los dos. GitHub y Stripe recomiendan hacerlo con una comparación de tiempo constante y no con un operador de igualdad simple.

El receptor debe conocer otras dos propiedades. Stripe advierte que un endpoint puede recibir de vez en cuando el mismo evento más de una vez, y que Stripe no garantiza el orden de los eventos. Stripe incluye además una marca de tiempo en la firma; sus bibliotecas rechazan por defecto los mensajes con más de cinco minutos de antigüedad, para frenar los mensajes reenviados.

• Comprobar la firma de cada mensaje entrante y descartar los que no tengan una firma válida.
• Comparar el hash en tiempo constante, no con un operador de igualdad simple.
• Responder 2xx enseguida y hacer el procesamiento real después, en una cola.
• Guardar el ID de cada evento y procesar solo una vez los que lleguen repetidos.
• En los eventos cuyo orden importa, consultar el estado actual por la API.
• Comprobar si el servicio reintenta las entregas fallidas y, si no lo hace, recuperar uno mismo los eventos perdidos.

• Mantener el endpoint sin comprobar la firma, de modo que cualquiera puede colar eventos falsos.
• Hacer un procesamiento largo antes de responder y superar así el tiempo límite del servicio.
• Tratar cada evento como único y crear, por ejemplo, un pedido dos veces.
• Dar por hecho que todos los servicios reintentan las entregas fallidas.
• Guardar la clave secreta en el código fuente o en un repositorio público.