Webhooks

Webhooks let your system receive job completion events without continuous polling.

How to Enable Webhooks

Include webhook_url in your run request:

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

Example:

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

Delivery Format

Armox sends:

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

Payload shape:

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

Signature Verification (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;
  }
}

Signature Verification (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

verify signature before processing payload
use raw request body for signature verification
process events idempotently (dedupe by job.id)
return 2xx quickly
move heavy processing to background workers
keep retry-safe webhook handlers

Suggested Handling Flow

Receive webhook request
Verify X-Armox-Signature
Validate JSON payload
Upsert job status in your database
Trigger downstream workflow (notification, asset indexing, etc.)
Return 200 quickly

Polling + Webhooks Together

For best reliability, use both:

webhook as primary event source
periodic reconciliation polling as fallback

See polling patterns in Jobs Endpoint.