Receptor de webhooks fiable: firma, idempotencia, cola y reintentos

Prompt

Actúa como ingeniero backend con experiencia en integraciones y sistemas distribuidos.

Necesito recibir webhooks de forma fiable:
- Proveedor y cómo firma las peticiones: {{proveedor}}
- Eventos que me interesan y qué hago con cada uno: {{eventos}}
- Stack: {{stack}}
- Sistema de colas disponible: {{cola}}

Entregables:
1. Diagrama en texto del flujo: recepción, verificación, persistencia, encolado, procesamiento, reintentos y cola de fallidos.
2. Endpoint receptor:
   - Lee el cuerpo en bruto antes de parsearlo y verifica la firma HMAC con comparación de tiempo constante.
   - Rechaza peticiones con marca de tiempo fuera de una ventana corta para evitar ataques de repetición.
   - Guarda el evento y responde 2xx en pocos milisegundos; nada de lógica pesada en la petición.
3. Idempotencia: tabla de eventos con el id del proveedor como clave única, estados (recibido, procesando, hecho, fallido) y cómo actuar si llega el mismo evento dos veces.
4. Worker: procesamiento con reintentos con backoff exponencial y jitter, límite de intentos, distinción entre errores transitorios y permanentes, y cola de mensajes fallidos con forma de reprocesarlos.
5. Orden de llegada: cómo tratar eventos desordenados (por ejemplo, comprobar la versión o la fecha del recurso o volver a consultar la API del proveedor).
6. Registro y alertas: qué registrar sin guardar datos sensibles y qué métricas vigilar.
7. Tests: firma válida e inválida, evento duplicado, marca de tiempo antigua, fallo transitorio que se recupera y fallo permanente que acaba en la cola de fallidos.
8. Cómo probarlo en local (túnel o reenvío de eventos) sin exponer el secreto.

Restricciones:
- No supongas el formato exacto de la firma ni los nombres de cabeceras del proveedor: si no te los doy, márcalos como [COMPLETAR] y dime dónde consultarlos en su documentación.
- El secreto se lee de variables de entorno o de un gestor de secretos, nunca en el código.
- Si falta información clave, pregúntame antes de escribir el código.

Cómo usarlo

Ejemplo de uso

Resultado de ejemplo

Pasarela → POST /webhooks/pagos → verificar firma y timestamp → INSERT evento (único)
        → commit → 200 → Celery: procesar → reintentos con backoff → dead-letter

@router.post("/webhooks/pagos")
async def recibir(request: Request, db: AsyncSession = Depends(get_db)) -> dict:
    cuerpo = await request.body()                     # cuerpo crudo, antes de parsear
    ts = request.headers.get("[COMPLETAR: cabecera de timestamp]", "")
    firma = request.headers.get("[COMPLETAR: cabecera de firma]", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        raise HTTPException(400, "timestamp ausente o caducado")

    # Formato del mensaje firmado según la documentación del proveedor: [COMPLETAR]
    esperada = hmac.new(settings.webhook_secret.encode(),
                        f"{ts}.".encode() + cuerpo, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(esperada, firma):      # comparación en tiempo constante
        raise HTTPException(400, "firma no válida")

    evento = json.loads(cuerpo)
    stmt = (insert(WebhookEvent)
            .values(provider_event_id=evento["id"], tipo=evento["type"],
                    payload=evento, estado="recibido")
            .on_conflict_do_nothing(index_elements=["provider_event_id"])
            .returning(WebhookEvent.id))
    nuevo_id = (await db.execute(stmt)).scalar_one_or_none()
    await db.commit()
    if nuevo_id is not None:                          # duplicado → no se encola de nuevo
        procesar_evento.delay(nuevo_id)
    return {"ok": True}

Datos clave

Categoría

Programación y desarrollo · APIs

Tipo de resultado

Código

Nivel

Avanzado

Pensado para

ChatGPT, Claude, Gemini y Microsoft Copilot

Verificado en

Pendiente de verificación editorial

Variables

Proveedor y firma, Eventos y acciones, Stack y Sistema de colas

Idioma

Español

Precio

Gratis, sin registro

Actualizado

07/11/2026

Preguntas frecuentes