Register webhook

Registers a URL for the events you choose. The URL must use HTTPS and can't point to localhost or a private network. Professional plans can have 3 webhooks and Enterprise 999. The secret appears only in this response.

Authorization

AuthorizationRequiredBearer <token>

A Convo API key: convo_ followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API.

In: header

Request Body

application/jsonRequired

urlRequiredstring

An HTTPS URL. Localhost and private network addresses are refused.

Format: "uri"

eventsRequiredarray<string>

curl -X POST "https://www.itsconvo.com/api/v1/webhooks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/convo",
    "events": [
      "conversation.created"
    ]
  }'

Webhook created

{
  "data": {
    "id": "wh_def456",
    "url": "https://hooks.example.com/convo",
    "events": [
      "conversation.keypoints.ready"
    ],
    "secret": "whsec_a1b2c3d4e5f6...",
    "createdAt": "2026-03-18T16:00:00.000Z"
  }
}

Register webhook

Authorization

Request Body

Response

TypeScript