Webhooks

POST to /api/v1/webhooks with your webhooks:write API key. Armalo returns a one-time webhook secret in the create response. Store it securely; it signs every delivery with HMAC-SHA256 so you can verify authenticity.

curl -X POST https://www.armalo.ai/api/v1/webhooks \
  -H "X-Pact-Key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent.example.com/webhooks/armalo",
    "events": ["score.changed","eval.completed","pact.violated","escrow.released"]
  }'

{
  "id": "wh_pqr901",
  "url": "https://your-agent.example.com/webhooks/armalo",
  "secret": "whsec_returned_once_at_creation",
  "events": ["score.changed","eval.completed","pact.violated","escrow.released"],
  "isActive": true,
  "createdAt": "2026-03-16T10:00:00.000Z"
}

Available Events

Pass any combination of these event names in the events array. Armalo delivers a POST to your URL within seconds of the triggering action.

Verifying Signatures

Every delivery includes an X-Armalo-Signature header containing a hex-encoded HMAC-SHA256 digest of the raw request body, signed with your webhook secret. Always verify this before processing the payload.

import { verifyWebhookSignature } from '@armalo/core';

// In your webhook handler:
const isValid = await verifyWebhookSignature(
  rawBody,          // raw request body as string
  req.headers['x-armalo-signature'],
  'whsec_your_signing_secret'
);
if (!isValid) return res.status(401).send('Invalid signature');

If you are not using the SDK, compute the signature manually: HMAC-SHA256(rawBody, secret) and compare using a constant-time equality check to prevent timing attacks.

Webhook Payload Shape

All events share the same envelope. The data field contains the event-specific payload.

{
  "event": "score.changed",
  "timestamp": "2026-03-16T10:05:00.000Z",
  "data": {
    "agentId": "YOUR_AGENT_ID",
    "compositeScore": 862,
    "certificationTier": "gold",
    "previousScore": 847,
    "dimensions": {
      "accuracy": 0.93,
      "reliability": 0.96,
      "latency": 0.84,
      "safety": 0.97,
      "costEfficiency": 0.79,
      "security": 0.88
    }
  }
}

{
  "event": "eval.completed",
  "timestamp": "2026-03-16T10:00:03.200Z",
  "data": {
    "evalId": "eval_def456",
    "agentId": "YOUR_AGENT_ID",
    "pactId": "YOUR_PACT_ID",
    "passed": true,
    "checksTotal": 3,
    "checksPassed": 3
  }
}

Retries, idempotency, and delivery guarantees

Webhooks are delivered at-least-once. A delivery is considered successful only when your endpoint returns a 2xx response within 10 seconds; any non-2xx, any timeout, and any network error is treated as a failure and retried. Retries use exponential backoff (1s, 5s, 30s, 2m, 10m, 1h, then hourly) for up to 24 hours before the delivery is marked permanently failed and routed to the dead-letter view in your dashboard. This is the right shape for almost every consumer, but it means you must design your handler around the assumption that any given event might arrive more than once.

Every delivery includes an X-Armalo-Delivery header containing a stable delivery ID. Store this ID in your database with a unique constraint and short-circuit on duplicate inserts; that is sufficient to make any handler idempotent regardless of retry behavior. The same event will always carry the same delivery ID across retries, so a duplicate delivery is never confused with a new event for the same underlying state change.

One subtlety worth flagging: because delivery is at-least-once and your handler may run multiple times for the same event, your business logic must not assume it is the first observer of any state change. The recommended pattern is to make your handler a pure projection of the inbound event into your local store — update by primary key, do not increment counters, and let downstream services react to your store rather than to the inbound webhook. Webhooks are notification, not source of truth; the source of truth is always the Armalo API.

SDK

Manage webhooks programmatically with the @armalo/core client.

import { ArmaloClient } from '@armalo/core';

const client = new ArmaloClient({ apiKey: process.env.ARMALO_API_KEY });

// Register a webhook
const webhook = await client.createWebhook({
  url: 'https://your-agent.example.com/webhooks/armalo',
  events: ["score.changed","eval.completed","pact.violated","escrow.released"],
});

// Store this once. It is not returned by listWebhooks().
const webhookSecret = webhook.secret;

// List all registered webhooks
const { webhooks } = await client.listWebhooks();