Webhooks

An endpoint receives every event below unless you choose a set when you register it. Register up to 10 endpoints per account in the console's Webhooks section.

• quota.threshold已达到配额阈值

  meter, threshold_percent, used and ceiling: an allowance passed one of its warning points.

• quota.exhausted配额已用尽

  meter, threshold_percent, used and ceiling: an allowance is spent.

• billing.transition账单状态已变更

  transition: what changed in the account's billing, as a stable key.

• key.created密钥已创建

  key: its id, name, prefix, last_four and environment. Never the secret.

• key.rotated密钥已轮换

  key (the new key), replaced_key_id and replaced_key_valid_until, when the old key stops working.

• key.revoked密钥已撤销

  key: the key that no longer works.

• key.expiring密钥已设为到期

  key and expires_at: support set the key to expire; create a replacement before then.

• attestation.reviewed已验证用途审核完成

  status, approved_use, review_note and reviewed_at: your verified-use declaration was reviewed.

• incident.published已发布事件通报

  incident: its reference, title, summary, status, impact, started_at and published_at. Sent to every account.

Each delivery is a POST with a JSON body: the event's fields plus type and created_at (ISO 8601). Any 2xx within 10 seconds counts as received; redirects are not followed.

• X-Wambesha-Signature

  t=<unix-seconds>,v1=<hex>: the time of this attempt and the signature.

• X-Wambesha-Event

  The event type, the same as the body's type.

• X-Wambesha-Delivery

  The delivery's id. Retries of one delivery repeat it, so use it to ignore a delivery you have already handled.

• User-Agent

  Wambesha-Webhooks/1.0.

{
  "key": {
    "id": "6f1d2c3a-4b5e-4f60-8a7b-9c0d1e2f3a4b",
    "name": "Production",
    "prefix": "wba_live_",
    "last_four": "9f2c",
    "environment": "LIVE"
  },
  "type": "key.created",
  "created_at": "2026-11-04T09:30:00Z"
}

Compute HMAC-SHA256 over the text <t>.<raw body>, keyed with your endpoint's signing secret as UTF-8 text, and compare its hex form with v1 in constant time. Use the body exactly as it arrived, before any JSON parsing. Refuse a t more than five minutes from your clock, so a recorded delivery cannot be replayed to you later.

# Check a delivery saved as body.json; SIG holds its X-Wambesha-Signature value.
t=${SIG#t=}; t=${t%%,*}
v1=${SIG##*v1=}
[ $(( $(date +%s) - t )) -le 300 ] && [ $(( t - $(date +%s) )) -le 300 ] || { echo "timestamp outside the five-minute window"; exit 1; }
expected=$({ printf '%s.' "$t"; cat body.json; } \
  | openssl dgst -sha256 -hmac "$WAMBESHA_WEBHOOK_SECRET" -hex | sed 's/^.*= //')
[ "$expected" = "$v1" ] && echo "valid" || echo "invalid"

A delivery that does not get a 2xx is tried again, up to 8 attempts in all. The waits after each failure double from 30 seconds: 30 s, 1 min, 2 min, 4 min, 8 min, 16 min and 32 min, so the last attempt comes about an hour after the first. A delivery that fails all 8 stays in the console's delivery log marked dead-lettered, where you can replay it. A destination we refuse to reach, such as one that resolves to a private address, is dead-lettered on its first attempt, without retries.

After 20 failed attempts in a row, across all its deliveries, an endpoint is disabled and shows so in the console with the time it happened. Any success resets the count, and so does turning the endpoint back on.

The console's delivery log keeps 30 days of deliveries. Replay sends a delivery's stored body again as a NEW delivery, with a new X-Wambesha-Delivery id and a fresh signature, so test your handler with a replay of a real event.