> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aegis-kyt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard self-service

> Manage webhook subscriptions from the Aegis app — register, test, inspect deliveries, rotate secrets, delete.  Equivalent to the /v1/webhooks REST surface but scoped to your subgroup rather than an API key.

<Note>
  **Surface:** `https://app.aegis-kyt.com/webhooks` · **Auth:** Aegis login (no API key needed for this flow)
</Note>

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](/webhooks/manage) — API-key based                                                  |
| A VASP / PSP using the app                                           | This page — subgroup-scoped via your login                                                                   |
| Both                                                                 | Both 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](/webhooks/events) 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**.

<Warning>
  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](#rotate-the-hmac-secret) action below
  instead of deleting + recreating the subscription.
</Warning>

## 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](/webhooks/manage#retry-schedule)
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).