Webhook vs API explicado con una tabla comparativa, las ventajas y desventajas de polling frente a push, un verificador de firmas HMAC en el navegador, gestión de reintentos y código receptor idempotente.
Con una llamada a una API, tu código pide datos a otro servicio cuando quiere: eso es pull. Con un webhook, el servicio envía un HTTP POST a tu URL en el momento en que pasa algo: eso es push. La mayoría de las integraciones usan ambos, un webhook para enterarse rápido de un cambio y una llamada a la API para obtener el registro completo y actual.
Petición a API vs webhook
Consultar una API cada minuto para ver si un pago se ha confirmado desperdicia peticiones y aun así llega tarde. Un webhook invierte la dirección, pero también te traslada la responsabilidad: tu endpoint tiene que ser público, demostrar que cada mensaje es auténtico, responder rápido y soportar que el mismo evento llegue dos veces. Esta página cubre cada una de esas tareas con código que puedes copiar.
En sentido amplio, sí. Es una petición HTTP con un cuerpo JSON, solo que enviada en la dirección contraria. A veces se le dice API inversa. La diferencia que importa es quién inicia la conversación y quién tiene que estar en línea para recibirla.
Usa webhooks cuando el proveedor los ofrezca para los eventos que necesitas y puedas alojar un endpoint HTTPS público. Haz polling cuando no haya webhook, cuando estés detrás de un firewall o para pocas comprobaciones en las que un minuto de retraso no importe.
La mayoría de los proveedores envían en una cabecera un HMAC SHA-256 del cuerpo, calculado con un secreto que solo conocéis tú y ellos. GitHub, por ejemplo, usa X-Hub-Signature-256 con el prefijo sha256=; Stripe usa Stripe-Signature con una marca de tiempo. Vuelve a calcularlo y compáralo antes de fiarte de nada.
La mayoría de los proveedores reintentan las entregas fallidas con intervalos cada vez mayores entre intentos, durante un periodo que depende del proveedor. Stripe, por ejemplo, sigue reintentando los eventos en modo live hasta tres días. Después, el evento solo está disponible a través de su API o su panel.
Los proveedores solo esperan la respuesta poco tiempo. Si tu código envía emails o consulta otros servicios primero, la entrega puede agotar el tiempo de espera y reintentarse aunque ya hayas actuado. Pon la tarea en cola, devuelve 200 y procésala después.
express.raw conserva el cuerpo como bytes para que la firma coincida. Este formato de cabecera sigue la convención sha256= de GitHub; adapta el nombre de la cabecera para otros proveedores.
Un índice único sobre el id del evento hace que una segunda entrega falle al insertarse, así que el trabajo se ejecuta una sola vez por muchas veces que llegue el evento.
ON CONFLICT DO NOTHING no devuelve ninguna fila para un duplicado, y tu código lo trata como ya gestionado.
El polling es más sencillo de alojar, pero más lento y genera más tráfico. Guarda un cursor para que cada consulta pida solo lo nuevo.
Pega un cuerpo y un secreto para calcular la firma que enviaría un proveedor, y luego pega la cabecera que recibiste para compararlas. Todo se ejecuta en tu navegador con la Web Crypto API; no se envía nada a ninguna parte.
Cuerpo de la petición en bruto
Secreto del webhook
Firma que debería llevar este cuerpo
Cabecera de firma que recibiste (opcional)
Coincide: el cuerpo y el secreto producen esta firma.
No coincide: el cuerpo ha cambiado, el secreto es incorrecto o la cabecera usa otro formato.
Calculando
Empieza gratis · Sin tarjeta de crédito