Webhooks

BossMode webhooks go two directions. Inbound events come from trusted partners — the primary example is AvatarCzar sending confidence updates when a persona’s read on the market changes. Outbound events go from BossMode to whatever URL you configure — Slack, a warehouse, your own service — when directives execute, packs install, revenue is recorded, or the guardian kill engages. Both directions are HMAC-SHA256 signed, timestamp-guarded to reject replays older than 5 minutes, and verified in constant time. Inbound endpoints resolve the sending customer from the payload’s identifier (not from the body’s customerId field) to block cross-tenant forgery. Outbound deliveries are at-least-once with exponential backoff — design handlers to be idempotent.

Inbound webhooks — AvatarCzar confidence updates

BossMode accepts inbound confidence update events from AvatarCzar at:

POST /api/pro/avatarczar/induction

Signature verification

Every inbound request from AvatarCzar is signed with HMAC-SHA256. The implementation is in lib/avatarczar-inbound.ts. The signature is delivered in the x-avatarczar-signature request header in the format:

x-avatarczar-signature: sha256=<hex-digest>

To verify:

import { verifyAvatarCzarInboundSignature } from '@/lib/avatarczar-inbound';

const valid = verifyAvatarCzarInboundSignature({
  secret: process.env.AVATARCZAR_WEBHOOK_SECRET!,
  rawBody: rawBodyString,  // the raw, un-parsed request body string
  signature: request.headers.get('x-avatarczar-signature'),
});

if (!valid) {
  return new Response('Unauthorized', { status: 401 });
}

Verification uses a constant-time comparison (crypto.timingSafeEqual) to prevent timing attacks.

Payload shape

The inbound payload is validated against the avatarCzarConfidenceUpdateSchema from lib/avatarczar-inbound.ts:

Field	Type	Description
`workspaceId`	`string`	The BossMode workspace receiving the update
`customerEntitlementId`	`string`	The entitlement being updated
`avatarczarTargetId`	`string`	The AvatarCzar target that generated the update
`avatarczarEventId`	`string`	Idempotency key — deduplicate on this field
`metric`	`enum`	The confidence metric being updated (see `ALLOWED_METRICS`)
`delta`	`number`	Signed delta applied to the metric
`newConfidence`	`number` (0–1)	The new confidence value after the update
`priorConfidence`	`number` (0–1)	Optional — the prior value before this update
`sourceBossmodeRef`	`object`	Optional — `{ table, id }` linking back to a BossMode record
`firedAt`	`number`	Unix timestamp (ms) when AvatarCzar fired the event

Rate limit

/api/pro/avatarczar/induction — 60 requests per 60 seconds.

Outbound webhooks — operator destinations

Configure outbound webhook destinations to receive BossMode events at your own endpoints.

Configuration endpoint

POST /api/pro/avatarczar/webhooks

Rate limit: 5 requests per 60 seconds.

Registering a destination

curl -sS -X POST https://bossmode.ing/api/pro/avatarczar/webhooks \
  -H "x-bossmode-token: $BOSSMODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Notify Slack when a directive completes",
    "url": "https://hooks.slack.com/services/T.../B.../..."
  }'

URLs are SSRF-validated before the config saves — private IPs, localhost, 169.254.0.0/16 metadata hosts, and non-HTTPS schemes are rejected.

Event types

Event	When
`directive.created`	A new boss directive is persisted
`directive.executed`	A directive completes (success or fail)
`pack.installed`	A pack fanout completes
`pack.revoked`	A pack license is refunded or disputed
`revenue.recorded`	A new revenue event is logged
`approval.requested`	An operator approval is queued
`kill.activated`	Guardian kill is engaged

Request format

POST https://your-endpoint.example.com/bossmode-webhook
X-BossMode-Signature: t=1712345678,v1=<hmac-sha256-hex>
X-BossMode-Event: directive.executed
X-BossMode-RequestId: req_...
Content-Type: application/json

{
  "event": "directive.executed",
  "timestamp": 1712345678123,
  "workspaceId": "...",
  "payload": { ... }
}

Verifying

import crypto from 'node:crypto';

function verifyBossModeSignature(rawBody: string, header: string, secret: string): boolean {
  const [tPart, v1Part] = header.split(',');
  const timestamp = Number.parseInt(tPart.split('=')[1], 10);
  const signature = v1Part.split('=')[1];

  // Reject events older than 5 minutes
  if (Math.abs(Date.now() - timestamp * 1000) > 5 * 60 * 1000) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
}

Retry policy

At-least-once delivery. Design handlers to be idempotent.
Up to 5 attempts with exponential backoff (1s → 10s → 60s → 10m → 1h).
Response 2xx = delivered. Any other status = retry. Response 410 Gone = permanent failure; retries stop.

Security

Outbound webhooks from BossMode are signed with HMAC-SHA256, using the same signing approach as AvatarCzar inbound events. Verify the X-BossMode-Signature header on your receiving endpoint.

Getting Started

Headless

Business Packs

Trust Intelligence

Governance

Daily Report

API Reference

Self-Hosting

Integrations

Agent Deployer

Webhooks

Webhooks

Inbound webhooks — AvatarCzar confidence updates

Signature verification

Payload shape

Rate limit

Outbound webhooks — operator destinations

Configuration endpoint

Registering a destination

Event types

Request format

Verifying

Retry policy

Security

​Webhooks

​Inbound webhooks — AvatarCzar confidence updates

​Signature verification

​Payload shape

​Rate limit

​Outbound webhooks — operator destinations

​Configuration endpoint

​Registering a destination

​Event types

​Request format

​Verifying

​Retry policy

​Security

Webhooks

Inbound webhooks — AvatarCzar confidence updates

Signature verification

Payload shape

Rate limit

Outbound webhooks — operator destinations

Configuration endpoint

Registering a destination

Event types

Request format

Verifying

Retry policy

Security