GuíasIntegraciones

Webhook: el principio y cómo recibirlo sin errores

Por el equipo de Banzai LabsActualizado el 2 min de lectura

Servicio Apayment.paidPOST{ JSON }FirmadoTu app200 OKSi no, reintentaTe avisa, no tienes que preguntar
Un webhook: el servicio te envía el evento en cuanto ocurre, firmado, y reintenta si falla.

El principio

Stripe, Shopify, GitHub o un servicio de firma electrónica envían un POST en JSON a la dirección que les das, en cada evento: payment.paid, order.created.

Las cuatro reglas de recepción

  1. 1Comprobar la firmaEl servicio firma cada mensaje con un secreto compartido. Sin firma válida, se rechaza.
  2. 2Responder rápidoUn 200 enseguida y el tratamiento después, en una cola.
  3. 3Tolerar duplicadosSe guarda el identificador de cada evento tratado.
  4. 4Registrarlo todoPara repetir un evento o entender un error.

Los errores frecuentes

Error Consecuencia
Sin comprobación de firma Cualquiera puede simular un pago
Tratamiento largo antes de responder El servicio cree que ha fallado y reenvía
Sin control de duplicados Un pedido enviado dos veces
Suponer el orden de los eventos Un estado antiguo sobrescribe el reciente

Para las automatizaciones, mira n8n, Make o a medida y Códigos HTTP.

Preguntas frecuentes

¿Webhook o API?
Con una API, preguntas «¿algo nuevo?» cada cierto tiempo. Con un webhook, el servicio te llama cuando hay algo nuevo. Menos llamadas, menos retraso.
¿Qué pasa si mi servidor está caído?
La mayoría de los servicios reintentan durante un tiempo. Prevé también una resincronización por la API para recuperar un evento perdido.
¿Por qué recibo dos veces el mismo evento?
Porque el servicio reintenta cuando no recibe respuesta a tiempo. Tu código debe reconocer un evento ya tratado e ignorarlo.

Para leer después

Todas las guías