Webhooks

Backend · devops · PHP · Computer Science
Acerca de webhooks - Documentación de GitHub Webhook- ¿Qué es y por qué lo necesitas- - Mailjet

Qué es un Webhook

Un webhook es una devolución de llamada HTTP: una petición HTTP POST enviada automáticamente cuando ocurre un evento en un sistema origen.
Es comunicación push, dirigida por eventos, sin polling.

El servidor origen inicia el envío de datos hacia un endpoint configurado por el cliente. Esto permite:

  • Actualizaciones automáticas y en tiempo real.
  • Notificaciones instantáneas de eventos (pagos, cambios de stock, reembolsos, registros de usuarios…).
  • Integraciones ligeras sin necesidad de consultar constantemente una API.

Webhooks vs API

  • Webhook
    • Push, evento → POST automático.
    • Notificaciones instantáneas.
    • Ideal para: cambios de precio, stock, pedidos, reembolsos, alertas.
    • Cliente escucha en una URL pública.
  • API
    • Pull, requiere realizar peticiones bajo demanda.
    • Mayor control, acceso directo a recursos y endpoints.
    • Se usa para operaciones CRUD o flujos que no dependen de eventos.

Diferencias clave

  • Origen de la comunicación:
    • API → cliente inicia.
    • Webhook → servidor inicia.
  • Frecuencia:
    • API → consultas periódicas (polling).
    • Webhook → solo cuando hay evento.
  • Escenarios:
    • Webhook → notificaciones.
    • API → obtener/actualizar datos bajo control del cliente.

Funcionamiento técnico

  • Protocolo: HTTP POST.
  • Contenido: JSON o XML.
  • Requisitos:
    • Endpoint accesible públicamente.
    • Validación de firma o secreto (HMAC).
    • Gestión de reintentos y verificación de idempotencia.
  • Seguridad:
    • HTTPS.
    • Tokens, timestamps, firmas.
    • IP allowlists.

Triggers y Eventos en Tiempo Real

Se activa un webhook cuando ocurre un evento predefinido, como:

  • Nuevo pedido.
  • Comentario creado.
  • Pago completado.
  • Actualización de stock.
  • Envío fallido de SMS.
  • Entrada en CRM.

El sistema destino procesa la notificación y realiza acciones automáticas.

Usos y Ejemplos Prácticos

  • Automatizaciones en CRM (actualizar contactos, crear leads).
  • Realizar pedidos o generar documentos automáticamente.
  • Generar presentaciones o informes al producirse un evento.
  • Notificaciones a Slack, paneles de control, email, WhatsApp.
  • Automatizar envíos de email (ej. botón en Notion → webhook → proveedor de email).
  • Registro histórico de eventos.
  • En WordPress con PHP para integraciones personalizadas.
  • Webhooks de SMS o telecomunicaciones.

Integraciones Populares

Webhooks y System Design

Basado en:
How WebHook works | System Design - YouTube

Aspectos clave:

  • Polling vs websockets vs webhooks.
  • Arquitectura dirigida por eventos (event-driven programming).
  • Cliente → escucha en URL.
  • Servidor → envía notificaciones.
  • Compatible con JSON, XML, formularios.
  • Casos: comments, orders, reservas, notificaciones de SMS.

Webhooks en WhatsApp API

Basado en:
TODO sobre los WEBHOOKS de la API WhatsApp - YouTube

  • Configurar webhook mediante ngrok o proxy.
  • Validar challenge de Meta.
  • Eventos: mensajes, estados de entrega, interacciones de plantillas.
  • Envío de plantilla para iniciar mensajes.
  • Integraciones comerciales:
    • [Wasapi Gestiona, Vende y Automatiza en WhatsApp con IA](https://www.wasapi.io/)

Open Source para Automatización

Funciones:

  • Router de condiciones.
  • Filtros.
  • Construcción visual de flujos.
  • Integraciones con más de 400 servicios.

Webhooks en .NET

Basado en:
What Exactly is a Webhook & How Do You Build One with .NET? 🚀 - YouTube

Incluye:

  • Controladores en ASP.NET Core.
  • Validación de firma.
  • Manejo de reintentos.
  • Serialización JSON.
  • Logging y auditoría.

Código de Ejemplo (Webhook Básico en .NET)

[ApiController]
[Route("webhooks")]
public class WebhookController : ControllerBase
{
	[HttpPost("receive")]
	public async Task<IActionResult> Receive([FromBody] object payload)
	{
		// Procesar evento
		Console.WriteLine(payload.ToString());

		// Respuesta requerida por algunos proveedores
		return Ok(new { status = "received" });
	}
}

`

Recursos en Video

Webhooks — Conceptos Avanzados y Faltantes

Entrega Fiable y Reintentos (Retry Strategy)

Los proveedores suelen implementar mecanismos automáticos para asegurar la entrega del webhook:

  • Backoff exponencial en los reintentos.
  • Límite máximo de intentos.
  • Registro de eventos fallidos en dead-letter queues.
  • Reenvío manual desde paneles de control.

Esto garantiza que una caída temporal del receptor no cause pérdida de eventos.

Idempotencia

Evita procesar un evento dos veces si el proveedor reenvía el webhook.

Estrategias:

  • Guardar el event_id en base de datos.
  • Ignorar eventos ya procesados.
  • Responder siempre 200 OK rápidamente, incluso si el procesamiento real continúa asíncronamente.

Procesamiento Asíncrono y Colas

Buenas prácticas para producción:

  • Validar el webhook y responder rápido.
  • Enviar el procesamiento a una cola como:
    • Redis Streams
    • RabbitMQ
    • Kafka
    • AWS SQS
    • Azure Service Bus

Esto evita timeouts y aumenta la fiabilidad del sistema.

Firmas Criptográficas y Seguridad Avanzada

Métodos habituales:

  • HMAC-SHA256 / SHA512 para firmar el payload.
  • Validación de timestamps para impedir replay attacks.
  • Cabeceras comunes:
    • X-Signature
    • X-Timestamp
    • X-Event-Type
  • Aislar el endpoint con:
    • HTTPS obligatorio.
    • Tokens de verificación.
    • IP allowlists.

Testing y Simulación de Webhooks

Herramientas útiles para pruebas:

  • ngrok → expone servidor local con túnel HTTPS.
  • Webhook.site → inspeccionar payloads en tiempo real.
  • RequestBin y Mockbin → endpoints temporales.
  • Test A/B: simular eventos y estructuras distintas.

Tipos de Webhooks

  • Sincrónicos: respuesta afecta el flujo del origen.
  • Asincrónicos: no dependen de la respuesta del receptor.
  • Batch webhooks: varios eventos dentro de un mismo payload.
  • Webhooks diferidos: solo notifican que hay actualización disponible.
  • Suscripción dinámica: endpoints generados según filtros o reglas.

Versionado y Migraciones

Buenas prácticas:

  • Header X-Webhook-Version.
  • Versionar esquema del JSON.
  • Tolerancia a campos desconocidos (forward compatibility).
  • Periodo de coexistencia entre versiones antiguas y nuevas.

Endpoints de Diseño

Ejemplos comunes:

  • /webhooks/events
  • /webhooks/payments
  • /webhooks/github
  • /webhooks/notifications

Características recomendadas:

  • Handshake inicial para validar endpoint.
  • Respuestas rápidas (máximo 3–5 segundos).
  • Logging detallado de cada recepción.

Observabilidad y Monitorización

Aspectos a cubrir:

  • Logs estructurados con request_id.
  • Dashboards de fallos y métricas.
  • Alertas cuando:
    • La tasa de errores sube.
    • Hay retrasos en reintentos.
    • Se reciben eventos duplicados.

Patrones Avanzados

  • Outbox Pattern: asegurar consistencia entre base de datos y eventos enviados.
  • Event Sourcing: almacenar el estado como secuencia de eventos.
  • State Reconciliation: reconciliar datos llamando a la API si falla un webhook.
  • Duplicate Suppression: descartar eventos repetidos o inconsistentes.