Webhooks

Um webhook é uma solicitação que a Ciarem envia ao seu servidor quando algo acontece na sua conta: um contato é criado, uma conversa é atribuída, um cliente escreve. Você informa uma URL à Ciarem, escolhe os eventos que interessam, e cada evento correspondente chega como um POST assinado em poucos segundos. Use webhooks quando quiser reagir às mudanças em vez de perguntar à API várias vezes se há algo novo. Usos típicos:

Manter seu próprio CRM ou data warehouse em dia com os contatos da Ciarem.
Avisar uma equipe no Slack quando uma conversa é atribuída ou encerrada.
Iniciar uma automação no seu backend quando um cliente envia uma mensagem.

Você não precisa de webhooks para usar a Ciarem. Eles são uma ferramenta para desenvolvedores que conectam a Ciarem aos seus próprios sistemas. Você precisa de um servidor que possa receber solicitações HTTPS da internet.

Antes de começar


Plano	Os webhooks fazem parte do acesso à API: Growth, Scale ou o teste gratuito.
Quem pode configurar	Os administradores da organização no painel, ou qualquer integração que tenha uma chave de API.
Seu endpoint	Uma URL HTTPS pública que responde a solicitações `POST`. Veja o que a Ciarem aceita.

Configure seu primeiro endpoint

No painel
Com a API

Abra Webhooks

Acesse Configurações, depois Webhooks, e clique em Adicionar endpoint.

Informe sua URL

Cole o endereço HTTPS do seu servidor em URL do endpoint. Adicione uma descrição se quiser lembrar para que serve o endpoint.

Escolha os eventos

Deixe Enviar todos os eventos ligado para receber tudo, incluindo os tipos de evento adicionados no futuro, ou desligue e marque só os eventos de que você precisa. Veja o catálogo de eventos.

Copie o segredo de assinatura

Depois de salvar, a Ciarem mostra o segredo de assinatura do endpoint. Ele começa com whsec_. Guarde-o no seu servidor: você o usa para conferir que cada solicitação vem mesmo da Ciarem. Você pode vê-lo de novo depois na página do endpoint com Mostrar segredo.

Envie um evento de teste

Abra o endpoint, escolha um evento em Evento de teste e clique em Enviar evento de teste. A Ciarem envia na hora e diz o que o seu servidor respondeu.

Crie o endpoint:

curl https://api.ciarem.ai/v1/webhook-endpoints \
  -H "Authorization: Bearer oak_SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/ciarem",
    "description": "Sync contacts to our CRM",
    "events": ["contact.created", "contact.updated", "contact.deleted"]
  }'

A resposta é o endpoint mais o seu segredo de assinatura:

{
  "id": "whe_…",
  "url": "https://example.com/hooks/ciarem",
  "description": "Sync contacts to our CRM",
  "events": ["contact.created", "contact.deleted", "contact.updated"],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-09T15:04:05.123456Z",
  "updated_at": "2026-10-09T15:04:05.123456Z",
  "secret": "whsec_…"
}

A API retorna secret apenas nesta resposta. Guarde-o agora. Um administrador ainda pode lê-lo depois no painel (Configurações → Webhooks → o endpoint → Mostrar segredo), mas nenhuma chamada da API o retorna de novo.

Depois envie um evento de teste para confirmar que o seu servidor o recebe:

curl -X POST https://api.ciarem.ai/v1/webhook-endpoints/whe_…/test \
  -H "Authorization: Bearer oak_SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "contact.created"}'

{
  "delivered": true,
  "response_status": 200,
  "error": null,
  "payload": { "id": "evt_test_…", "type": "contact.created", "…": "…" }
}

Para receber todos os tipos de evento, incluindo os adicionados depois, envie "events": ["*"]. O * deve ser o único item da lista.

O que a Ciarem envia

Cada evento é uma solicitação POST com um corpo JSON:

POST /hooks/ciarem HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Ciarem-Webhooks/1.0 (+https://ciarem.ai)
Ciarem-Signature: t=1760022245,v1=5f8a…c2e1

{"id":"evt_…","type":"contact.created","api_version":"v1","created_at":"2026-10-09T15:04:05.123456Z","data":{"contact":{"id":"cnt_…","first_name":"Ana","…":"…"}}}

Parte	O que é
`Ciarem-Signature`	A prova de que a solicitação vem da Ciarem e não foi alterada. Verifique antes de confiar no corpo.
`id`	O id único do evento. O mesmo evento sempre carrega o mesmo `id`, também quando é enviado de novo. Use-o para ignorar duplicados.
`type`	Qual é o evento, por exemplo `contact.created`. Veja o catálogo de eventos.
`api_version`	Sempre `v1` hoje.
`created_at`	Quando o evento aconteceu na Ciarem, em UTC.
`data`	Os detalhes. O formato depende de `type`.

O que o seu servidor deve fazer

Responda com um status 2xx em até 10 segundos. Qualquer 2xx conta como recebido. Qualquer outra coisa, incluindo um redirecionamento, um timeout ou um erro de conexão, conta como falha e passa por novas tentativas.
Verifique a assinatura antes de agir sobre o corpo. Veja Verificar assinaturas.
Responda primeiro, trabalhe depois. Se tratar um evento leva tempo, salve-o em uma fila e retorne 200 na hora. A Ciarem não lê o corpo da sua resposta.
Espere duplicados e eventos fora de ordem. O mesmo evento pode chegar mais de uma vez, e dois eventos podem chegar em uma ordem diferente daquela em que aconteceram. Veja Duplicados e ordem.
Ignore o que você não reconhece. Novos tipos de evento e novos campos são adicionados com o tempo. Pule valores de type desconhecidos com um 200, e não rejeite corpos com campos a mais.

Requisitos da URL

A Ciarem só envia para URLs que é seguro chamar a partir da internet pública:

A URL deve começar com https://. http:// simples é recusado.
O host deve resolver para um endereço IP público. localhost, faixas de rede privada (como 10.x.x.x ou 192.168.x.x) e endereços link-local são recusados, tanto quando você salva o endpoint quanto em cada entrega.
Seu servidor deve apresentar um certificado TLS válido para esse hostname.
Redirecionamentos não são seguidos. Um 301 ou 302 é registrado como entrega com falha, então cadastre a URL final.
A URL pode ter até 2.048 caracteres e pode incluir um caminho, uma porta e uma query string.

Para testar com um servidor no seu próprio computador, exponha-o por um túnel que dê a você um endereço HTTPS público, como o ngrok ou o Cloudflare Tunnel, e cadastre a URL do túnel.

Limites


Endpoints por organização	10
Tempo de resposta permitido	10 segundos
Novas tentativas de uma entrega com falha	Por até 3 dias, veja Novas tentativas
Registro de entregas guardado por	30 dias
Tamanho da descrição	500 caracteres

Próximos passos

Catálogo de eventos

Cada tipo de evento e o corpo exato que ele carrega.

Verificar assinaturas

Confira que uma solicitação vem da Ciarem, com código que você pode copiar.

Entregas e novas tentativas

Novas tentativas, o registro de entregas, enviar novamente e solução de problemas.

Primeiros passos

Canais

Seu agente de IA

Usando a Ciarem

Integrações

App móvel

Faturamento

API para desenvolvedores

Antes de começar

Configure seu primeiro endpoint

O que a Ciarem envia

O que o seu servidor deve fazer

Requisitos da URL

Limites

Próximos passos

Catálogo de eventos

Verificar assinaturas

Entregas e novas tentativas

​Antes de começar

​Configure seu primeiro endpoint

​O que a Ciarem envia

​O que o seu servidor deve fazer

​Requisitos da URL

​Limites

​Próximos passos

Catálogo de eventos

Verificar assinaturas

Entregas e novas tentativas

Antes de começar

Configure seu primeiro endpoint

O que a Ciarem envia

O que o seu servidor deve fazer

Requisitos da URL

Limites

Próximos passos