Webhooks

Los webhooks permiten que tu sistema reciba eventos de finalización de jobs sin necesidad de polling continuo.

Cómo Habilitar Webhooks

Incluye webhook_url en tu solicitud de ejecución:

POST /api/v1/models/run
POST /api/v1/apps/run

Ejemplo:

{
  "model": "google/nano-banana",
  "input": { "prompt": "..." },
  "webhook_url": "https://your-app.com/webhooks/armox"
}

Formato de Entrega

Armox envía:

Método: POST
Encabezado: X-Armox-Signature: sha256=<signature>
Content-Type: application/json

Estructura del payload:

{
  "event": "job.completed",
  "job": {
    "id": "job_456",
    "status": "completed",
    "output": {
      "outputImage": "https://..."
    },
    "completed_at": "2026-03-26T12:45:00.000Z"
  }
}

Verificación de Firma (Node.js)

import crypto from "crypto";

export function verifyArmoxSignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !signatureHeader.startsWith("sha256=")) return false;

  const received = signatureHeader.slice("sha256=".length);
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  try {
    return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  } catch {
    return false;
  }
}

Verificación de Firma (Python)

Prompt Template

import hmac
import hashlib

def verify_armox_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not signature_header.startswith("sha256="):
        return False

    received = signature_header[len("sha256="):]
    expected = hmac.new(
        key=secret.encode("utf-8"),
        msg=raw_body,
        digestmod=hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(received, expected)

Mejores Prácticas

verifica la firma antes de procesar el payload
usa el cuerpo de la solicitud sin procesar para la verificación de firma
procesa los eventos de forma idempotente (deduplica por job.id)
devuelve 2xx rápidamente
mueve el procesamiento pesado a workers en segundo plano
mantén los handlers de webhooks seguros ante reintentos

Flujo de Gestión Sugerido

Recibe la solicitud del webhook
Verifica X-Armox-Signature
Valida el payload JSON
Actualiza o inserta el estado del job en tu base de datos
Activa el flujo de trabajo posterior (notificación, indexación de assets, etc.)
Devuelve 200 rápidamente

Polling + Webhooks Juntos

Para mayor fiabilidad, usa ambos:

webhook como fuente principal de eventos
polling periódico de reconciliación como respaldo

Consulta los patrones de polling en Endpoint de Jobs.