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

# Webhook endpoints

> Register the URLs Agentcard delivers events to, choose the events, and rotate signing secrets.

A **webhook endpoint** is a URL you own plus the list of events it should receive. Agentcard signs every delivery with the endpoint's secret, which is returned once at creation and can be rotated. Endpoints are mode-scoped: a sandbox token manages sandbox endpoints, a production token manages production ones.

`enabled_events` accepts concrete event types (`vault.card_stored`) or wildcards (`checkout_authorization.*`). Events emitted today: `connection.created`, `wallet_link.opened`, `vault.session_linked`, `vault.card_stored`, `checkout_authorization.approved|submitted|declined|expired|amount_mismatch`, `order.placed|failed|confirmed`, `identity.verification.updated`, `connected_card.updated`, `card.created|updated|closed`, `transaction.authorized|cleared|declined|voided`, `approval.requested`.

## The webhook endpoint object

| Field            | Type           | Description                                                           |
| ---------------- | -------------- | --------------------------------------------------------------------- |
| `object`         | string         | `webhook_endpoint`                                                    |
| `id`             | string         | `we_…`                                                                |
| `url`            | string         | Where events are delivered. HTTPS.                                    |
| `enabled_events` | string\[]      | Event types or wildcards (`checkout_authorization.*`).                |
| `status`         | string         | `active` or `disabled`.                                               |
| `description`    | string or null |                                                                       |
| `secret`         | string         | Only on the create response and `GET …/secret`. Signs every delivery. |

```json theme={null}
{
  "id": "we_7h2k9p4m",
  "object": "webhook_endpoint",
  "url": "https://your.app/agentcard/webhooks",
  "enabled_events": ["vault.card_stored", "checkout_authorization.*"],
  "status": "active",
  "description": "Production checkout events"
}
```

## Endpoints

| Endpoint                                          |                                                                                                   |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `GET /api/v2/webhook_endpoints`                   | [List webhook endpoints](/api-reference/webhook-endpoints/list)                                   |
| `POST /api/v2/webhook_endpoints`                  | [Create a webhook endpoint](/api-reference/webhook-endpoints/create): the secret is returned once |
| `GET /api/v2/webhook_endpoints/{id}`              | [Get a webhook endpoint](/api-reference/webhook-endpoints/get)                                    |
| `PATCH /api/v2/webhook_endpoints/{id}`            | [Update a webhook endpoint](/api-reference/webhook-endpoints/update)                              |
| `DELETE /api/v2/webhook_endpoints/{id}`           | [Delete a webhook endpoint](/api-reference/webhook-endpoints/delete)                              |
| `GET /api/v2/webhook_endpoints/{id}/secret`       | [Get the signing secret](/api-reference/webhook-endpoints/secret)                                 |
| `POST /api/v2/webhook_endpoints/{id}/roll_secret` | [Rotate the signing secret](/api-reference/webhook-endpoints/roll-secret)                         |
| `GET /api/v2/webhook_endpoints/{id}/deliveries`   | [List recent deliveries](/api-reference/webhook-endpoints/deliveries)                             |

The same router also answers at `/api/v1/webhook_endpoints`; both addresses are one resource. For the envelope, signature verification, and every event payload, see the [Webhooks](/webhooks/overview) tab.