¿Qué son los Webhooks?

Un webhook es un callback HTTP automatizado: cuando ocurre un evento, un sistema envía un POST con el payload a una URL que otro sistema registró. El término — acuñado en 2007 como “user-defined HTTP callbacks” — nombra la inversión que importa: en lugar de que tu sistema pregunte una y otra vez si algo cambió, el otro sistema le avisa al tuyo en el momento en que cambia. Es push construido con las piezas más simples de la web: una URL HTTPS, un POST, un cuerpo JSON y un 2xx de confirmación.

Puntos clave

La entrega, de punta a punta

CONFIG    el receptor expone  https://api.example.com/hooks/payments
          y la registra con el proveedor, eligiendo eventos + un secret

EVENTO    un cobro se aprueba en el proveedor

ENTREGA   POST /hooks/payments
          webhook-id: evt_8fk2            ← clave de deduplicación
          webhook-timestamp: 1767024900   ← guardia anti-replay (dentro de la firma)
          webhook-signature: v1,d2Vio…    ← HMAC-SHA256(secret, id.timestamp.body)
          { "type": "charge.succeeded", "orderId": "o-1187" }

ACK       el receptor verifica la firma → 200 en segundos → el trabajo corre async
RETRY     ¿sin 2xx? backoff exponencial por horas/días → los duplicados son NORMALES

Ambas direcciones del patrón en código — un trigger de datos como emisor, una Cloud Function como receptor y el cliente solo mirando el resultado:

// JavaScript — Cloud Code (cloud/main.js): both directions of a webhook
// OUTGOING: any data change can notify an external system
Parse.Cloud.afterSave('Order', async (req) => {
  if (req.object.get('status') !== 'paid') return;
  await Parse.Cloud.httpRequest({
    method: 'POST',
    url: 'https://hooks.example.com/orders', // the receiver's registered URL
    headers: { 'Content-Type': 'application/json' },
    body: { event: 'order.paid', id: req.object.id },
  });
});

// INCOMING: a Cloud Function is a ready-made webhook receiver
Parse.Cloud.define('paymentWebhook', async (req) => {
  verifySignature(req.params, process.env.WEBHOOK_SECRET); // HMAC first
  await markOrderPaid(req.params.orderId); // write fast, work async
  return { received: true }; // 2xx before heavy processing
});

// Flutter / Dart — Back4app Flutter SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
final orderQuery = QueryBuilder<ParseObject>(ParseObject('Order'))
  ..whereEqualTo('objectId', orderId);
final sub = await LiveQuery().client.subscribe(orderQuery);
sub.on(LiveQueryEvent.update, (order) {
  if (order.get<String>('status') == 'paid') showReceipt();
});
// The webhook itself was handled server-side — clients just watch the data.

// iOS / Swift — Back4app Swift SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
let orderQuery = Order.query("objectId" == orderId)
let sub = try await orderQuery.subscribe()
sub.handleEvent { _, event in
    if case .updated(let order) = event, order.status == "paid" {
        showReceipt()
    }
}
// The webhook itself was handled server-side — clients just watch the data.

// Android / Kotlin — Back4app Android SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
val orderQuery = ParseQuery.getQuery<ParseObject>("Order")
orderQuery.whereEqualTo("objectId", orderId)
val sub = ParseLiveQueryClient.Factory.getClient().subscribe(orderQuery)
sub.handleEvent(SubscriptionHandling.Event.UPDATE) { _, order ->
    if (order.getString("status") == "paid") showReceipt()
}
// The webhook itself was handled server-side — clients just watch the data.

Webhooks vs. APIs vs. polling

El debate es en gran parte falso: las integraciones maduras usan los tres — webhooks para enterarse rápido de los cambios, llamadas de API para traer el estado autoritativo y actuar, y un poll lento de reconciliación como la red bajo el trapecio.

El checklist del receptor

La lista que la documentación de cada proveedor dispersa y ningún explicador reúne:

1. Verifica el HMAC sobre el cuerpo crudo — antes de parsear; el JSON re-serializado rompe las firmas.
2. Compara en tiempo constante — la igualdad de strings filtra timing; usa el comparador de tu biblioteca de criptografía.
3. Aplica la ventana de timestamp — rechaza entregas de más de ~5 minutos; como el timestamp está dentro del contenido firmado, un atacante no puede reproducir una solicitud vieja válidamente firmada con un reloj fresco.
4. Devuelve 2xx rápido — en segundos, antes del trabajo pesado; los handlers lentos sufren timeout y se reintentan hasta volverse tormentas de duplicados.
5. Procesa de forma asíncrona — encola, confirma y luego trabaja.
6. Deduplica por ID de evento — con una memoria al menos tan larga como la ventana de retry del proveedor.
7. No confíes en el payload para acciones críticas — trata el webhook como un timbre; trae el estado actual desde la API del proveedor antes de despachar mercancía o conceder acceso.
8. Registra las entregas y alerta sobre fallas — el silencio es indistinguible de un endpoint roto.

Una nota de desarrollo local que las páginas de definición se saltan: localhost es inalcanzable desde internet, así que el desarrollo pasa por una herramienta de túnel que le presta a tu máquina una URL pública, más una herramienta de captura para reproducir payloads reales.

Semántica de entrega, con honestidad

La entrega de webhooks es at-least-once: el proveedor reintenta hasta recibir confirmación, así que los duplicados son una característica de la confiabilidad, no un bug en ella — la entrega exactly-once sobre una red no confiable es formalmente imposible, y el equivalente práctico es at-least-once más tu handler idempotente. El orden no está garantizado: los retries y los envíos en paralelo se intercalan, así que updated puede llegar antes que created; aplica los eventos por ID y versión, o vuelve a traer el estado. Y las ventanas de retry se acaban: un endpoint caído durante un fin de semana puede perder eventos de forma permanente, y por eso las integraciones críticas donde hay dinero de por medio combinan webhooks con reconciliación periódica — la misma disciplina de at-least-once que los brokers formalizan, llegando por HTTP plano. La comparación generaliza: un webhook es push punto a punto hacia una URL conocida; pub/sub agrega un broker, topics y fan-out; WebSockets y SSE sirven a clientes, no a servidores. Los webhooks son la respuesta específicamente cuando dos sistemas que no comparten infraestructura necesitan enterarse de los eventos del otro.

Construir el lado del emisor

Emitir webhooks con confiabilidad es un pequeño sistema en sí mismo, y ninguna página de ranking lo esboza: una cola por destino, para que un endpoint muerto no bloquee al resto; retries con backoff exponencial y jitter; un almacén de dead-letter con herramientas de reenvío para cuando los intentos se agotan; firma HMAC con secretos por endpoint y rotación; suscripciones por tipo de evento, para que los receptores opten solo por lo que quieren; y logs de entrega que tus clientes puedan leer, porque “¿lo enviaron?” es la primera pregunta de soporte. Un punto de seguridad exclusivo del emisor: los receptores registran URLs arbitrarias, así que valídalas contra rangos de direcciones internas — un atacante que registra http://10.0.0.5/admin como su “endpoint de webhook” es server-side request forgery disfrazado de funcionalidad de integración.

Casos de uso comunes

• Ciclos de vida de pagos — cobros, reembolsos y cambios de suscripción anunciados a tu backend a medida que se liquidan.
• Disparadores de CI/CD — el cableado canónico del git push que arranca un build.
• Automatización entre apps — herramientas de formularios, plataformas de chat y CRMs encadenados a través de los eventos de los demás.
• Notificaciones operativas — alertas de monitoreo y actualizaciones de entrega aterrizando en los canales del equipo.
• Sincronización de datos — mantener al día un espejo local de un sistema aliado sin hacer polling de toda su API.

¿Deberías usar un webhook? Matriz de decisión

Limitaciones y trade-offs

• La entrega es best-effort más allá de la ventana de retry. Los webhooks notifican; no garantizan. Los polls de reconciliación respaldan todo lo que no puede perderse.
• El receptor hereda el deber de uptime. La disponibilidad de tu endpoint ahora condiciona los eventos de otra persona — deploys, cold starts y timeouts se convierten en bugs de integración.
• La seguridad es opt-in. Un endpoint de webhook sin verificación es una API de escritura sin autenticación; el checklist de HMAC es la diferencia entre integración e inyección.
• El debugging atraviesa dos empresas. Logs de entrega en ambos lados y herramientas de replay son lo que convierte “no llegó” de un punto muerto en un diff.
• Los payloads derivan. Los proveedores versionan los esquemas de eventos; los consumidores anclados a formas exactas se rompen en silencio — parsea a la defensiva e ignora los campos desconocidos.

Webhooks en Back4app

Back4app es una plataforma open-source de Backend as a Service (BaaS) que combina base de datos gestionada, APIs REST y GraphQL generadas automáticamente, autenticación, almacenamiento de archivos y funciones serverless con Cloud Code. Ambas mitades del patrón están a un constructo de Cloud Code de distancia, como muestran las pestañas de código. Saliente: un trigger afterSave que observa tus datos llama a Parse.Cloud.httpRequest hacia cualquier URL registrada — tu app se convierte en proveedor de webhooks escribiendo la función, y las disciplinas del lado del emisor (retry ante fallas, log de entregas) viven en el mismo archivo. Entrante: una Cloud Function expuesta por HTTPS es un receptor listo para usar — verifica el HMAC contra un secreto en la configuración del servidor, escribe el resultado en la base de datos, devuelve rápido — y la actualización luego se propaga a cada pantalla abierta vía Live Queries, completando el ciclo que va del evento en una plataforma de pagos al recibo del usuario sin un servidor que operar en ninguno de los dos extremos.