Express.js
Explica cómo recibir webhooks con raw body, verificar firmas, controlar replay, persistir idempotencia y responder rápido antes del procesamiento.
Un webhook es una entrada pública controlada por otro sistema. Debe verificar autenticidad, tolerar reintentos y separar la recepción rápida del procesamiento durable.
Un proveedor externo envía un evento HTTP cuando ocurre algo relevante: un pago fue aprobado, un archivo terminó de procesarse o una entrega cambió de estado. El receptor no controla cuándo llega, cuántas veces se repite ni el orden exacto.
El modelo seguro es:
raw body
↓
verificar firma y timestamp
↓
validar envelope
↓
deduplicar event id
↓
persistir o encolar
↓
responder 2xx rápido
↓
procesar de forma asíncronaSin webhook, la aplicación tendría que consultar periódicamente al proveedor. Esto añade latencia y carga. El webhook invierte la dirección: el proveedor notifica.
El coste es abrir una ruta pública que recibe input no confiable y puede ser atacada, duplicada o entregada fuera de orden.
Muchos proveedores calculan un HMAC sobre los bytes exactos del body y un timestamp.
app.post(
'/webhooks/payments',
express.raw({ type: 'application/json', limit: '1mb' }),
paymentWebhookHandler,
);El parser raw debe ejecutarse antes de express.json() para esa ruta. Si el body se parsea y serializa de nuevo, espacios, orden o encoding pueden cambiar y la firma dejará de coincidir.
Ejemplo conceptual:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verifySignature(rawBody: Buffer, timestamp: string, signature: string) {
const payload = `${timestamp}.${rawBody.toString('utf8')}`;
const expected = createHmac('sha256', process.env.WEBHOOK_SECRET!)
.update(payload)
.digest('hex');
const receivedBuffer = Buffer.from(signature, 'hex');
const expectedBuffer = Buffer.from(expected, 'hex');
return receivedBuffer.length === expectedBuffer.length &&
timingSafeEqual(receivedBuffer, expectedBuffer);
}En producción debes seguir exactamente el esquema del proveedor, validar encoding y evitar comparaciones normales que filtren tiempo.
Una firma válida no garantiza que el evento sea reciente. Un atacante podría reenviar una request capturada.
Controles habituales:
La ventana temporal reduce replay, pero el reloj del sistema debe estar sincronizado.
Los proveedores reintentan cuando no reciben 2xx o la conexión falla. Incluso una respuesta correcta puede perderse en red.
Por eso el consumidor debe asumir entrega at least once.
CREATE TABLE received_webhook_events (
provider text NOT NULL,
event_id text NOT NULL,
received_at timestamptz NOT NULL DEFAULT now(),
payload jsonb NOT NULL,
PRIMARY KEY (provider, event_id)
);La unique constraint convierte la deduplicación en una garantía concurrente. Un Set en memoria falla al reiniciar o escalar.
Un evento posterior puede llegar antes que uno anterior. No actualices estado únicamente por orden de recepción.
Posibles estrategias:
El endpoint no debería ejecutar procesos largos antes de responder. Cada segundo aumenta probabilidad de timeout y retry.
async function paymentWebhookHandler(request, response) {
const event = verifyAndParse(request.body, request.headers);
const accepted = await webhookInbox.accept(event);
response.sendStatus(accepted ? 202 : 200);
}El inbox persiste el evento; un worker lo procesa después. 202 puede ser adecuado si el proveedor lo acepta, pero algunos proveedores exigen cualquier 2xx específico. Sigue su contrato.
HTTP endpoint
↓ transaction
webhook_inbox row
↓ worker
aplicar cambio de dominio
↓
marcar processed / retry / dead-letterPersistir antes de responder evita perder el evento entre acknowledgment y enqueue. Si insertas en DB y publicas a una cola separada, considera patrón outbox o un mecanismo transaccional equivalente.
Responde 400 o 401 según contrato, registra metadata segura y no procesa.
Puede responderse 2xx e ignorarse para evitar retries eternos, dependiendo del proveedor.
Si el evento ya quedó persistido, responde 2xx y reintenta internamente.
Mueve a dead-letter, alerta y conserva suficiente contexto para investigar.
Un proveedor confirma un pago de una orden:
(provider, eventId) con unique constraint.pending → paid sea válida.Si el webhook llega dos veces, la segunda inserción no crea otro pago.
Mide:
Prueba:
Rompe la representación firmada.
Produce timeouts y duplicados.
Crea pagos o acciones repetidas.
No funciona entre instancias ni reinicios.
Provoca retries innecesarios.
Idempotencia en operaciones HTTP generaliza la protección contra retries a comandos iniciados por clientes.