Register a webhook endpoint

POST/webhooks

Requires scope: manage:webhooks

Parameters

Parameter	In	Type	Description
`Idempotency-Key`required	header	string	Stable logical request ID required for every machine mutation; exact retries replay and changed inputs conflict.

Request body

Field	Type	Allowed values	Description
`url`required	string	any string	https only
`event_types`	"deal.created" \| "deal.updated" \| "deal.stage_changed" \| "contact.created" \| "store.entered" \| "store.exited" \| "store.signal" \| "watch.health_changed"[]	any "deal.created" \| "deal.updated" \| "deal.stage_changed" \| "contact.created" \| "store.entered" \| "store.exited" \| "store.signal" \| "watch.health_changed"[]	Omit for all current events

Responses

Status	Description
`201`	Created (secret shown once)
`400`	Invalid url / event types
`401`	Missing or invalid API key
`403`	Key lacks the required scope
`429`	Rate limit exceeded (see Retry-After)

Is this page helpful?

Request

curl -X POST "https://vergio.ai/api/v1/webhooks" \
  -H "Authorization: Bearer $VERGIO_API_KEY" \
  -H "Idempotency-Key: replace-with-a-stable-request-id" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/vergio-events",
  "event_types": [
    "deal.created"
  ]
}'

Response (201)

{
  "endpoint": {
    "id": "b7c9a2e1-0000-4000-8000-000000000000",
    "url": "string",
    "eventTypes": [
      "string"
    ],
    "active": true,
    "createdAt": "2026-07-06T12:00:00Z"
  },
  "secret": "string"
}