Skip to main content
POST
/
api
/
v1
/
webhook_endpoints
curl -X POST https://api.agentcard.sh/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/agentcard",
    "enabled_events": ["card.*", "transaction.authorized"],
    "description": "production receiver"
  }'

{
  "id": "wh_abc123",
  "object": "webhook_endpoint",
  "url": "https://your-app.example.com/webhooks/agentcard",
  "enabled_events": ["card.*", "transaction.authorized"],
  "status": "active",
  "description": "production receiver",
  "api_version": null,
  "consecutive_failures": 0,
  "last_success_at": null,
  "disabled_at": null,
  "created_at": "2026-05-17T12:00:00.000Z",
  "updated_at": "2026-05-17T12:00:00.000Z",
  "secret": "whsec_3a4b5c6d7e8f…"
}
Creates a new webhook endpoint for your organization. The response includes a signing secret that is shown only once — store it securely.

​
Request body

​
url
string
required
HTTPS URL we will POST events to. http://localhost is allowed for local development.
​
enabled_events
array of strings
required
Event types to subscribe to. Supports exact names (card.created), prefix wildcards (card.*), and the catch-all (*). See the event catalog for the full list.
​
description
string
Free-form description, up to 255 characters.
​
api_version
string
Optional API-version pin. Reserved for future use; ignore for now.

​
Response

​
id
string
Unique endpoint identifier.
​
object
string
Always "webhook_endpoint".
​
url
string
The endpoint URL.
​
enabled_events
array of strings
The event subscriptions, normalized.
​
status
string
"active" (always, on creation).
​
secret
string
The HMAC signing secret (whsec_…). Returned on creation for convenience. If you lose it, recover via GET /:id/secret or rotate with POST /:id/roll_secret. Treat like a password — every retrieval is audited.
​
created_at
string
ISO 8601 creation timestamp.
curl -X POST https://api.agentcard.sh/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/agentcard",
    "enabled_events": ["card.*", "transaction.authorized"],
    "description": "production receiver"
  }'

{
  "id": "wh_abc123",
  "object": "webhook_endpoint",
  "url": "https://your-app.example.com/webhooks/agentcard",
  "enabled_events": ["card.*", "transaction.authorized"],
  "status": "active",
  "description": "production receiver",
  "api_version": null,
  "consecutive_failures": 0,
  "last_success_at": null,
  "disabled_at": null,
  "created_at": "2026-05-17T12:00:00.000Z",
  "updated_at": "2026-05-17T12:00:00.000Z",
  "secret": "whsec_3a4b5c6d7e8f…"
}