Webhook
Webhook
¿Qué es un webhook?
- El servidor avisa primero cuando ocurre un evento
- «API inversa»
- Útil para la integración en tiempo real
Al incorporar el webhook cambia quién inicia la acción. Con el método de sondeo (polling), nuestro servidor consulta la API de la pasarela de pagos cada minuto para preguntar «¿hay pagos nuevos?». Aunque pregunte 1,440 veces al día, solo se obtienen unas decenas de pagos reales y el resto son consultas vacías. Con el webhook desaparecen esas preguntas inútiles y el tiempo desde que ocurre un evento hasta que se procesa pasa de minutos a segundos. Además, las consultas vacías que consumían el límite de llamadas a la API desaparecen por completo, y con ello bajan los costos del servidor y los puntos de falla.
Antes de conectarlo, hay que atender cuatro puntos: verificación de firma, velocidad de respuesta, reintentos y procesamiento idempotente. La mayoría de los servicios envían una firma HMAC en el encabezado de la solicitud, así que hay que compararla con la clave secreta para descartar las solicitudes falsas. Además, el receptor normalmente debe devolver un 200 OK en 3 a 5 segundos. Las tareas pesadas, como descontar inventario o enviar correos, conviene ponerlas en una cola y responder primero. Si falla, el proveedor vuelve a enviarlo varias veces con intervalos de minutos a horas, por eso hay que asegurarse de que aunque llegue dos veces el mismo ID de evento, el pedido se registre una sola vez.
Si se distingue bien de herramientas parecidas, el diseño resulta más sencillo. Una API normal es una ventanilla a la que recurrimos cuando la necesitamos, pero el webhook es un aviso que el otro sistema envía una sola vez; si no se procesa en el momento en que llega, se pierde. Si el objetivo es actualizar pantallas en tiempo real, conviene SSE o WebSocket; si hay que acumular cientos de miles de eventos al día en orden, es mejor una cola de mensajes como Kafka o SQS. El webhook es la herramienta intermedia más adecuada para la entrega de eventos de unos miles al día.
Lo que más se rompe en la práctica es la creencia de que «el webhook llega una sola vez y en el orden en que se envió». Por reenvíos y problemas de red, la misma notificación de pago completado llega dos veces: se generan dos pedidos y el inventario se descuenta dos veces, y eso ocurre de verdad. Como el servidor receptor está detrás del firewall de la empresa, también es común que las notificaciones que llegaban bien en desarrollo no lleguen ni una sola vez en producción. Hay que partir de que el webhook es un aviso que a veces se pierde, y en los eventos que involucran dinero, una conciliación diaria del libro mayor (consulta de datos) permite detectar los casos que quedaron sin registrar durante la noche.
Seolyeong ParkCon 17 años de experiencia práctica y más de 200 sesiones impartidas, especialista en IA generativa y transformación digital (AX), que logra que personas sin formación técnica la usen desde el primer día
John KimAutor de «Diseño de marketing B2B» y CEO de Nanum Consultoría, instructor John KimEl término fue propuesto en 2007 por Jeff Lindsay y se extendió como una forma de integración web que envía datos automáticamente cuando ocurre un evento.
Veamos un caso hipotético. Se trata de la empresa A, que opera su propia tienda en línea, tiene 52 colaboradores y ventas anuales de KRW 18,000,000,000 (≈ US$13,472,400). Como verificaba si el pago estaba completo en lotes cada 5 minutos, la orden tardaba en promedio 7 minutos en llegar al almacén, y el servicio de atención recibía cada semana 40 consultas del tipo «Ya pagué, ¿por qué sigue en proceso?». Un equipo de desarrollo de 4 personas dedicó 3 semanas a cambiar al webhook de pagos.
- En la primera reunión, Kim, subgerente y jefe del equipo de desarrollo, lo resumió así: "En lugar de preguntar cada cinco minutos, cambiemos para que la pasarela de pagos avise primero", y después registró la URL de recepción en el panel de administración de la PG (pasarela de pagos).
- El responsable de backend, Lee, incorporó la lógica de verificación de firma HMAC y, tras ejecutar 20 pagos de prueba, confirmó que 2 solicitudes falsas con firma no coincidente quedaron bloqueadas.
- Al segundo día de operación llegaron tres veces seguidas el mismo evento de pago y los pedidos se duplicaron; el asistente de gerencia Lee fijó event_id como clave única en la base de datos y lo cambió para que a partir de la segunda vez solo responda 200 OK y lo ignore.
- Como las respuestas superaban los 6 segundos y la tasa de fallos por tiempo de espera subió al 4%, se pasaron a una cola el descuento de inventario y el envío de correos de confirmación, y el servidor responde en cuanto recibe la solicitud. Así, la tasa de fallos bajó al 0.2%.
- Tres semanas después de la migración, el tiempo promedio hasta la orden de despacho bajó de 7 minutos a 12 segundos, las consultas de atención al cliente pasaron de 40 a 6 por semana, y las 8,640 llamadas diarias de sondeo (polling) llegaron a 0.