> ## Documentation Index
> Fetch the complete documentation index at: https://help.ciarem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Faça a Ciarem enviar uma solicitação HTTPS ao seu servidor no momento em que um contato, uma conversa ou uma mensagem muda.

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](https://help.ciarem.ai/pt/api-reference/quickstart.md) 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.

> [!NOTE]
>
> 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](https://help.ciarem.ai/pt/api-reference/authentication.md). |
| **Seu endpoint** | Uma URL **HTTPS** pública que responde a solicitações `POST`. Veja [o que a Ciarem aceita](#requisitos-da-url). |

## Configure seu primeiro endpoint

**No painel**

**1. Abra Webhooks**

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

**2. 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.

**3. 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](https://help.ciarem.ai/pt/webhooks/events.md).

**4. 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](https://help.ciarem.ai/pt/webhooks/signatures.md). Você pode vê-lo de novo depois na página do endpoint com **Mostrar segredo**.

**5. 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.

**Com a API**

Crie o endpoint:

```bash theme={null}
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:

```json theme={null}
{
  "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_…"
}
```

> [!WARNING]
>
> 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:

```bash theme={null}
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"}'
```

```json theme={null}
{
  "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:

```http theme={null}
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](https://help.ciarem.ai/pt/webhooks/signatures.md) 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](https://help.ciarem.ai/pt/webhooks/deliveries.md#duplicados-e-ordem). |
| `type` | Qual é o evento, por exemplo `contact.created`. Veja o [catálogo de eventos](https://help.ciarem.ai/pt/webhooks/events.md). |
| `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

1. **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](https://help.ciarem.ai/pt/webhooks/deliveries.md#novas-tentativas).
2. **Verifique a assinatura** antes de agir sobre o corpo. Veja [Verificar assinaturas](https://help.ciarem.ai/pt/webhooks/signatures.md).
3. **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.
4. **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](https://help.ciarem.ai/pt/webhooks/deliveries.md#duplicados-e-ordem).
5. **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.

> [!TIP]
>
> 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](https://help.ciarem.ai/pt/webhooks/deliveries.md#novas-tentativas) |
| Registro de entregas guardado por | 30 dias |
| Tamanho da descrição | 500 caracteres |

## Próximos passos

> **[Catálogo de eventos](https://help.ciarem.ai/pt/webhooks/events.md)**
>
> Cada tipo de evento e o corpo exato que ele carrega.

> **[Verificar assinaturas](https://help.ciarem.ai/pt/webhooks/signatures.md)**
>
> Confira que uma solicitação vem da Ciarem, com código que você pode copiar.

> **[Entregas e novas tentativas](https://help.ciarem.ai/pt/webhooks/deliveries.md)**
>
> Novas tentativas, o registro de entregas, enviar novamente e solução de problemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.