En lugar de que clientes pregunten constantemente "¿hay novedades?", tú les notificas cuando ocurren. Eso es webhooks.
Webhooks: callbacks HTTP para eventos
Un webhook es: cuando ocurre X, POST a esta URL con los datos. Simple y poderoso. El cliente se registra una vez, tu aplicación lo notifica cada vez que ocurra el evento.
- Cliente registra: POST /webhooks/subscribe {evento: payment.completed, url: ...}.
- Cuando ocurre evento, POST a URL con datos.
- Cliente procesa en su servidor, responde 2xx.
Fiabilidad: que los webhooks se entreguen
No todos los webhooks se entregan a la primera. Red falla, servidor cliente está caído. Necesitas reintentos con backoff exponencial.
También necesitas registro de qué webhooks se intentaron, fallaron, etc. Para debugging y auditoría.
- Intenta envío inmediato.
- Si falla, reintenta después 5 minutos, después 1 hora, después 1 día.
- Registra estado de cada intento.
Seguridad: verifica que webhooks son reales
Cualquiera puede hacer POST a URL del cliente fingiendo ser tu servicio. La solución es firmar webhooks: incluir HMAC-SHA256 signature de los datos.
Cliente valida firma usando su secret compartido contigo. Si no coincide, sabe que es fake.
- Genera signature con HMAC usando secret compartido.
- Envía en header X-Webhook-Signature.
- Cliente verifica firma antes de procesar.
Idempotencia: procesa mismo webhook dos veces sin problema
Si envío webhook dos veces (porque el cliente no respondió la primera vez y reintentó), debe ser seguro procesarlo dos veces.
La forma es incluir ID único en webhook. Cliente guarda qué webhooks procesó, si ve duplicado, ignora.
Un webhook confiable debe tolerarse procesado múltiples veces sin efectos secundarios duplicados.
Alternativa: colas de eventos internas
Para sistemas internos, en lugar de webhooks HTTP, usa colas como RabbitMQ, Kafka. Más confiable, baja latencia, fácil de escalar.
Webhooks son para externos. Eventos internos pueden usar infraestructura más sofisticada.