Webhooks API

Endpoints

Method	Path	Description
`GET`	`/api/v1/webhooks`	List webhook endpoints
`POST`	`/api/v1/webhooks`	Create endpoint
`GET`	`/api/v1/webhooks/{id}`	Get endpoint
`PATCH`	`/api/v1/webhooks/{id}`	Update URL, events, or secret
`DELETE`	`/api/v1/webhooks/{id}`	Delete endpoint
`POST`	`/api/v1/webhooks/{id}/test`	Send test event

Requires API key or session auth.

Create webhook

POST /api/v1/webhooks
Authorization: Bearer ch_live_xxx
Content-Type: application/json

{
  "url": "https://hooks.yourbusiness.com/chatevo",
  "events": [
    "conversation.created",
    "message.created",
    "assistant.updated"
  ],
  "description": "CRM sync"
}

Response includes a signing_secret — store it immediately; it is shown only once.

{
  "id": "wh_6tU9vW2x",
  "url": "https://hooks.yourbusiness.com/chatevo",
  "events": ["conversation.created", "message.created", "assistant.updated"],
  "signing_secret": "whsec_abc123…",
  "status": "active"
}

Event types

Event	When fired
`conversation.created`	New conversation started
`conversation.updated`	Metadata or status changed
`conversation.closed`	Conversation archived
`message.created`	User or assistant message added
`assistant.updated`	Assistant config changed
`knowledge_base.indexed`	KB finished indexing
`tool.execution_failed`	Tool call failed at runtime

Delivery format

Each delivery is an HTTP POST to your URL with JSON body:

{
  "id": "evt_1yZ3aB5c",
  "type": "message.created",
  "created_at": "2026-07-16T10:20:00Z",
  "data": {
    "id": "msg_4pQ8rS2t",
    "conversation_id": "conv_8mN4pQ1r",
    "role": "user",
    "content": "Do you ship to Canada?"
  }
}

Signature headers

Header	Description
`X-Chatevo-Signature`	HMAC-SHA256 of raw body
`X-Chatevo-Timestamp`	Unix timestamp of delivery
`X-Chatevo-Event`	Event type string

Verify every payload — see Webhook HMAC.

Retries

Failed deliveries (non-2xx or timeout > 5s) retry with exponential backoff for up to 72 hours. Subject to webhook rate limits.

Test delivery

POST /api/v1/webhooks/wh_6tU9vW2x/test

Sends a ping event to verify URL reachability and signature validation on your side.