Webhooks

Les webhooks permettent à votre système de recevoir les événements de complétion des jobs sans polling continu.

Comment activer les webhooks

Incluez webhook_url dans votre requête d'exécution :

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

Exemple :

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

Format de livraison

Armox envoie :

Méthode : POST
En-tête : X-Armox-Signature: sha256=<signature>
Content-Type : application/json

Structure du payload :

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

Vérification de la signature (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;
  }
}

Vérification de la signature (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)

Bonnes pratiques

vérifiez la signature avant de traiter le payload
utilisez le corps brut de la requête pour la vérification de la signature
traitez les événements de manière idempotente (déduplication par job.id)
retournez un 2xx rapidement
déplacez le traitement lourd vers des workers en arrière-plan
gardez des handlers de webhook résistants aux tentatives

Flux de traitement recommandé

Recevez la requête webhook
Vérifiez X-Armox-Signature
Validez le payload JSON
Mettez à jour le statut du job dans votre base de données (upsert)
Déclenchez le workflow en aval (notification, indexation des assets, etc.)
Retournez 200 rapidement

Polling + Webhooks ensemble

Pour une fiabilité optimale, utilisez les deux :

le webhook comme source principale d'événements
un polling de réconciliation périodique comme solution de secours

Consultez les schémas de polling dans Endpoint Jobs.