Skip to main content
Surface: https://app.aegis-kyt.com/webhooks · Auth: Aegis login (no API key needed for this flow)
The dashboard at /webhooks is the subgroup-scoped alternative to the /v1/webhooks/* REST endpoints. If you use Aegis through the web app (KYT, /tx-check, /tx-alerts), your subscriptions live under your subgroup and don’t require minting a separate API key just to receive events.

​
When to use which surface

You are…Use this surface
An x402 paying consumer (AI agent, integration without a UI session)Manage via /v1/webhooks — API-key based
A VASP / PSP using the appThis page — subgroup-scoped via your login
BothBoth work; subscriptions are independent — events fan out to ALL matching subscriptions across both surfaces
The events fired are identical regardless of ownership path. See Event schemas for payload details.

​
Register a subscription

  1. Sign in at https://app.aegis-kyt.com and open Webhooks from the sidebar.
  2. Choose your subgroup (if you’re a member of more than one; single-membership users auto-select).
  3. Paste your HTTPS endpoint URL — must respond 2xx within 10 seconds.
  4. Select which events to subscribe to (any non-empty subset):
    • tx.policy.alert.triggered — KYT alerts (recommended)
    • aegis.bfs.completed / aegis.bfs.failed — exposure jobs
    • aegis.check.high_risk — standalone address screens
  5. Click Create subscription.
The full HMAC signing secret is shown ONCE in a copy-to-clipboard banner right after creation. Save it to your server-side config immediately — it’s not visible after you navigate away. If you lose it, use the Rotate secret action below instead of deleting + recreating the subscription.

​
Test a delivery

Every active subscription has a Test button on the list view. Clicking it dispatches a synthetic event with the same shape as a real one (payload.synthetic = true). Your endpoint receives it within seconds; verify the signature works end-to-end before you wait for real traffic. The test endpoint at the platform level is POST /api/webhooks/test, which proxies to the same backend used for POST /v1/webhooks/{id}/test.

​
Inspect delivery history

Click History on any subscription to open /webhooks/{id}/deliveries — the last 100 delivery attempts with:
  • Status: delivered (2xx) · pending (queued, not tried yet) · failed (5xx/4xx/timeout, will retry) · gave_up (retries exhausted)
  • HTTP code returned by your endpoint
  • Error text (network reason, parse error) or a 200-char preview of the payload that was sent
  • Attempt counter — 1 = first try, 5 = give-up boundary
Use this when:
  • Your case-review queue is missing alerts (“did Aegis even send it?”)
  • You’re rolling out a new endpoint and want to confirm shape
  • You’re investigating a gave_up cluster to see what your endpoint returned

​
Rotate the HMAC secret

Click the rotate icon on a subscription. We mint a fresh 256-bit secret server-side; the same one-time copy banner surfaces it. Recommended sequence to avoid dropped events:
  1. Add the NEW secret to your endpoint’s accepted-secrets list (most verifying libraries accept multiple).
  2. Click rotate in the dashboard.
  3. Confirm the next live delivery verifies with the NEW secret.
  4. Remove the OLD secret from your endpoint.
If your verifier only supports one secret at a time, expect a brief window where deliveries arriving between the rotate click and your endpoint redeploy will fail verification — they retry, so as long as your endpoint redeploys within the retry window nothing is lost.

​
Delete a subscription

Click the trash icon and confirm. Active deliveries already enqueued may still fire (worker-side race window); subscribe to a fresh URL if you need to fully cut off old deliveries to a deprecated endpoint.

​
RBAC

All actions above require membership in the subgroup that owns the subscription. Group admins of the subgroup, or platform super-admins, can also act. Non-members trying to act on someone else’s subscription get a 404 (we don’t leak the subscription’s existence to non-owners).