Webhooks

Receive signed, replayable notifications when catalog facts or lifecycle state change.

Event types

catalog.release.published

A new immutable catalog snapshot is available.

deployment.changed

Price, capability, limit, evidence, region, or lifecycle metadata changed.

deployment.deprecated

A deployment entered the deprecated lifecycle state.

evidence.stale

Evidence crossed the freshness threshold configured for the subscription.

Event payload

{
  "id": "evt_01JZ8R4Y8QH2M0N7K3V5T1P9CE",
  "type": "deployment.changed",
  "created_at": "2026-07-16T09:42:11Z",
  "catalog_release": "cat_2026_07_16_31dd0ab92e80",
  "data": {
    "deployment_id": "dep_openai_gpt_5_1_responses_global",
    "changed_fields": ["rate_card.output_micro_usd"]
  }
}

Verify signatures

Read the raw request body and the allm-signature header, parse t and v1, compute HMAC-SHA256 using the endpoint secret, compare signatures in constant time, and reject timestamps outside your replay window. Do not parse or transform the body before verification.

signed = timestamp + "." + rawBody
expected = hmacSha256(endpointSecret, signed)

if !constantTimeEqual(expected, signature): reject(401)
if abs(now - timestamp) > 5 minutes: reject(401)

Delivery behavior

Return a 2xx quickly and process events asynchronously. Deduplicate on event id. Delivery order is not guaranteed. ALLM makes six total attempts with exponential backoff, disables the endpoint after the final failure, and preserves the dead letter for an audited staff replay.