Webhooks

Webhooks ermöglichen es Ihrem System, Job-Abschluss-Events zu empfangen, ohne kontinuierlich pollen zu müssen.

Webhooks aktivieren

Fügen Sie webhook_url in Ihrer Ausführungsanfrage ein:

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

Beispiel:

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

Zustellungsformat

Armox sendet:

Methode: POST
Header: X-Armox-Signature: sha256=<signature>
Content-Type: application/json

Payload-Struktur:

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

Signaturverifizierung (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;
  }
}

Signaturverifizierung (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)

Best Practices

Signatur vor der Verarbeitung des Payloads verifizieren
Rohen Request Body für die Signaturverifizierung verwenden
Events idempotent verarbeiten (Deduplizierung nach job.id)
Schnell 2xx zurückgeben
Aufwändige Verarbeitung in Hintergrund-Worker auslagern
Webhook-Handler retry-sicher gestalten

Empfohlener Verarbeitungsablauf

Webhook-Anfrage empfangen
X-Armox-Signature verifizieren
JSON-Payload validieren
Job-Status in Ihrer Datenbank aktualisieren (Upsert)
Nachgelagerten Workflow auslösen (Benachrichtigung, Asset-Indexierung usw.)
Schnell 200 zurückgeben

Polling + Webhooks kombiniert

Für optimale Zuverlässigkeit verwenden Sie beides:

Webhook als primäre Event-Quelle
Periodisches Reconciliation-Polling als Fallback

Polling-Muster finden Sie unter Jobs-Endpunkt.