Klivo Chat API › Application APIs

Webhooks

Configure endpoints para receber notificações em tempo real dos eventos do Klivo Chat.

⚡

Webhooks são a forma mais eficiente de integrar o Klivo Chat com sistemas externos. Em vez de consultar a API periodicamente, você recebe os dados no momento exato em que o evento ocorre.

GET

Listar Webhooks

Retorna todos os webhooks configurados na conta.

GET
https://chat.klivo.marketing/api/v1/accounts/{account_id}/webhooks
Parâmetros de Path
account_id integer obrigatório
ID da conta.
CURL 
curl --request GET \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/webhooks \
  --header 'api_access_token: '
200 
{
  "data": [
    {
      "id": 1,
      "url": "https://meuservidor.com/webhook",
      "subscriptions": [
        "conversation_created",
        "message_created",
        "conversation_resolved"
      ]
    }
  ]
}
POST

Criar Webhook

Cadastra um novo endpoint de webhook.

POST
https://chat.klivo.marketing/api/v1/accounts/{account_id}/webhooks
Parâmetros de Path
account_id integer obrigatório
ID da conta.
Body Parameters
url string obrigatório
URL HTTPS que receberá as notificações POST.
subscriptions array obrigatório
Eventos para assinar. Opções: conversation_created, conversation_updated, conversation_resolved, message_created, contact_created, contact_updated, webwidget_triggered.
CURL 
curl --request POST \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/webhooks \
  --header 'api_access_token: ' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://meuservidor.com/webhook",
  "subscriptions": [
    "conversation_created",
    "message_created"
  ]
}'
200 
{
  "id": 1,
  "url": "https://meuservidor.com/webhook",
  "subscriptions": ["conversation_created", "message_created"]
}
PATCH

Atualizar Webhook

Atualiza a URL ou os eventos de um webhook.

PATCH
https://chat.klivo.marketing/api/v1/accounts/{account_id}/webhooks/{webhook_id}
Parâmetros de Path
account_id integer obrigatório
ID da conta.
webhook_id integer obrigatório
ID do webhook.
Body Parameters
url string
Nova URL do endpoint.
subscriptions array
Nova lista de eventos.
CURL 
curl --request PATCH \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/webhooks/{webhook_id} \
  --header 'api_access_token: ' \
  --header 'Content-Type: application/json' \
  --data '{
  "subscriptions": [
    "conversation_created",
    "message_created",
    "contact_created"
  ]
}'
200 
{
  "id": 1,
  "url": "https://meuservidor.com/webhook",
  "subscriptions": ["conversation_created", "message_created", "contact_created"]
}
DELETE

Excluir Webhook

Remove um webhook da conta.

DELETE
https://chat.klivo.marketing/api/v1/accounts/{account_id}/webhooks/{webhook_id}
Parâmetros de Path
account_id integer obrigatório
ID da conta.
webhook_id integer obrigatório
ID do webhook.
CURL 
curl --request DELETE \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/webhooks/{webhook_id} \
  --header 'api_access_token: '
200 
{
  "message": "Webhook deleted"
}

Estrutura do payload

O Klivo Chat envia os dados em formato JSON via POST para a URL cadastrada. Exemplo para message_created:

Payload de exemplo 
{
  "event": "message_created",
  "id": "101",
  "content": "Olá, preciso de ajuda!",
  "message_type": "incoming",
  "created_at": "2026-05-01T14:30:00Z",
  "conversation": {
    "id": 42,
    "status": "open",
    "inbox_id": 1
  },
  "contact": {
    "id": 17,
    "name": "João Silva",
    "phone_number": "+5511999990001"
  },
  "account": {
    "id": 1,
    "name": "Minha Empresa"
  }
}
⚠️

Seu endpoint deve responder com status 200 em até 10 segundos. Após 3 falhas consecutivas, o webhook é desativado automaticamente.