> ## 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.

# Create a webhook endpoint

> Register a URL and the events it receives. The signing secret is returned once.

<ParamField body="url" type="string" required>An HTTPS URL you control.</ParamField>
<ParamField body="enabled_events" type="string[]" required>Event types or wildcards, at least one. Unknown types are rejected.</ParamField>
<ParamField body="description" type="string">Up to 255 characters.</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.agentcard.sh/api/v2/webhook_endpoints \
    -H "Authorization: Bearer $ORG_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://your.app/agentcard/webhooks", "enabled_events": ["vault.card_stored", "checkout_authorization.*"], "description": "Production checkout events"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 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",
    "secret": "whsec_…"
  }
  ```
</ResponseExample>

Store `secret` now. It is not returned again except through [Get the signing secret](/api-reference/webhook-endpoints/secret). The token decides the endpoint's mode, never the body.