Entregas e novas tentativas

Uma entrega é um evento a caminho de um endpoint. Se três dos seus endpoints estão inscritos em contact.created, um contato novo gera três entregas, cada uma acompanhada e tentada de novo por conta própria.

O que conta como entregue

A Ciarem envia o evento no momento em que ele acontece, normalmente em poucos segundos, e espera até 10 segundos pela resposta do seu servidor.

Seu servidor	Resultado
Responde com qualquer status `2xx`	Entregue. A Ciarem não lê o corpo da resposta.
Responde com `3xx`, `4xx` ou `5xx`	Falhou. Redirecionamentos não são seguidos.
Demora mais de 10 segundos	Falhou.
Recusa a conexão, tem um certificado TLS inválido ou não pode ser resolvido	Falhou.

Uma entrega com falha é tentada de novo automaticamente.

Novas tentativas

Depois de uma falha, a Ciarem espera e tenta de novo, com uma espera maior a cada vez:

Tentativa	Espera depois da falha anterior
2ª	1 minuto
3ª	5 minutos
4ª	30 minutos
5ª	2 horas
6ª em diante	8 horas cada

As novas tentativas continuam até a entrega ter 3 dias. Depois disso a Ciarem desiste dela e a marca como Falhou. Na prática são cerca de 14 tentativas. As novas tentativas rodam uma vez por minuto, então uma tentativa pode começar até um minuto depois do horário agendado. Cada tentativa envia o mesmo corpo com o mesmo id de evento. Só o cabeçalho Ciarem-Signature muda, porque cada tentativa é assinada com um timestamp novo.

Status das entregas

No painel	Na API	Significado
Pendente	`pending`	Na fila, ainda sem tentativa, ou na fila para ser enviada novamente.
Entregue	`succeeded`	Seu servidor respondeu `2xx`.
Tentando novamente	`failed`	A última tentativa falhou. Outra está agendada para `next_attempt_at`.
Falhou	`exhausted`	A Ciarem parou de tentar: a entrega passou de 3 dias, ou o endpoint dela foi desativado.

Quando um endpoint continua falhando

Se todas as entregas para um endpoint falham por 3 dias seguidos, a Ciarem desliga o endpoint. No painel ele aparece como Desativado por falhas repetidas; na API, enabled é false e disabled_reason é auto_failures. Uma única entrega bem-sucedida zera a contagem, então um endpoint com falhas ocasionais nunca é desativado. Enquanto um endpoint está desativado:

Nada é enviado para ele, e os eventos que acontecem nesse meio-tempo não são guardados para depois.
As entregas que aguardavam uma nova tentativa são marcadas como Falhou.

Para ligá-lo de novo, corrija o seu servidor e depois escolha Ativar no menu do endpoint, ou envie PATCH /v1/webhook-endpoints/{id} com {"enabled": true}. A entrega recomeça com os eventos novos a partir desse ponto. Para recuperar o que você perdeu, veja Recuperar o atraso depois de uma queda.

Pausar um endpoint por conta própria

Escolha Desativar no menu do endpoint, ou envie {"enabled": false}, para parar as entregas sem excluir o endpoint. Ele se comporta como no caso automático: nada é enviado enquanto está desligado, as novas tentativas pendentes são descartadas, e ativá-lo depois não reenvia eventos antigos. disabled_reason é user. Excluir um endpoint também exclui o registro de entregas dele.

Se o seu plano mudar

Os webhooks fazem parte do acesso à API. Se a sua organização passar para um plano sem ele, ou se um teste terminar sem uma assinatura, a Ciarem para de enviar eventos imediatamente. Seus endpoints são mantidos, e as entregas recomeçam sozinhas quando você volta ao Growth ou ao Scale. Os eventos que aconteceram nesse intervalo não são enviados depois.

Duplicados e ordem

Construa o seu handler em torno de dois fatos: O mesmo evento pode chegar mais de uma vez. A Ciarem garante que cada evento é entregue pelo menos uma vez, não exatamente uma vez. A causa mais comum é uma nova tentativa depois que o seu servidor processou o evento mas respondeu devagar demais. Faça com que tratar o evento seja seguro de repetir:

Guarde o id de cada evento que você processa e pule qualquer id que já tenha visto. Guardar os ids por alguns dias é suficiente, já que as novas tentativas param depois de 3 dias.
Ou torne a própria ação repetível, por exemplo “definir a etapa do contato como X” em vez de “avançar o contato uma etapa”.

Os eventos podem chegar fora de ordem. Um evento tentado de novo chega depois de outros mais novos, e dois eventos com segundos de diferença podem trocar de lugar. Não presuma que o último evento que você recebeu é o estado mais recente:

Compare created_at no envelope, ou updated_at no contato, com o que você já guardou, e ignore os dados mais antigos.
Para conversas, espere que messages.inbound possa chegar antes do conversation.created da mesma conversa.
Quando a ordem importa, trate o evento como um sinal e leia o estado atual pela API.

O registro de entregas

Cada entrega dos últimos 30 dias fica registrada, com o corpo exato que foi enviado. No painel: abra Configurações → Webhooks e clique em um endpoint. A tabela Entregas mostra cada evento, o status dele, o código de resposta do seu servidor e o número de tentativas. Clique em uma linha para ver o corpo que foi enviado, o id do evento, a resposta do seu servidor ou o erro, e a última e a próxima tentativa. Com a API:

curl "https://api.ciarem.ai/v1/webhook-endpoints/whe_…/deliveries?status=failed&limit=50" \
  -H "Authorization: Bearer oak_SEU_SEGREDO"

{
  "items": [
    {
      "id": "whd_…",
      "endpoint_id": "whe_…",
      "event_id": "evt_…",
      "event_type": "contact.updated",
      "status": "failed",
      "attempt_count": 3,
      "next_attempt_at": "2026-10-09T15:40:05.123456Z",
      "last_attempt_at": "2026-10-09T15:10:05.123456Z",
      "response_status": 500,
      "error": "endpoint answered 500",
      "created_at": "2026-10-09T15:04:05.123456Z",
      "payload": { "id": "evt_…", "type": "contact.updated", "…": "…" }
    }
  ],
  "next_cursor": null
}

Parâmetro
`status`	Opcional. Um de `pending`, `succeeded`, `failed`, `exhausted`.
`limit`	Opcional. De 1 a 100, padrão 20.
`cursor`	Opcional. O `next_cursor` da página anterior. Os resultados vêm do mais novo para o mais antigo.

response_status é null quando o seu servidor nunca respondeu (um timeout ou um erro de conexão); nesse caso error diz o que deu errado. Duas coisas não estão no registro: os eventos de teste, e as entregas sobre um contato que depois foi apagado de forma permanente, que são removidas junto com os dados do contato.

Enviar uma entrega novamente

Você pode reenviar qualquer entrega do registro, seja qual for o status dela, por exemplo depois de corrigir um bug no seu handler.

No painel: clique na entrega para abri-la e depois clique em Enviar novamente.
Com a API: POST /v1/webhook-deliveries/{delivery_id}/redeliver.

A entrega volta para Pendente e é enviada em menos de um minuto, com o mesmo corpo e o mesmo id de evento. Como o id não muda, um handler que remove duplicados vai pulá-la: apague esse id do seu lado antes se quiser que ela seja processada de novo. Enviar novamente é recusado com 409 endpoint_disabled enquanto o endpoint está desligado. Ative-o primeiro.

Recuperar o atraso depois de uma queda

As novas tentativas cobrem quedas de até 3 dias. Para algo mais longo, ou para o tempo em que um endpoint ficou desativado, faça a conciliação pela API:

Contatos: liste-os com GET /v1/contacts e compare updated_at com o que você tem.
Conversas: liste-as com GET /v1/conversations e leia as mensagens das que mudaram.

Uma conciliação periódica como esta é uma boa prática mesmo quando tudo funciona. Ela protege você de bugs do seu lado que os webhooks sozinhos não conseguem revelar.

Gerenciar endpoints com a API

Tudo o que há no painel também está disponível para uma chave de API. Os detalhes completos de solicitação e resposta estão na referência da API, em Webhooks.

Solicitação	O que faz
`GET /v1/webhook-endpoints`	Lista os seus endpoints.
`POST /v1/webhook-endpoints`	Cria um endpoint e retorna o segredo de assinatura dele.
`GET /v1/webhook-endpoints/{id}`	Lê um endpoint.
`PATCH /v1/webhook-endpoints/{id}`	Altera `url`, `description`, `events` ou `enabled`. Envie só os campos a alterar.
`DELETE /v1/webhook-endpoints/{id}`	Exclui o endpoint e o registro de entregas dele.
`POST /v1/webhook-endpoints/{id}/test`	Envia um evento de teste agora e retorna a resposta do seu servidor.
`GET /v1/webhook-event-samples`	Retorna o corpo de exemplo de cada tipo de evento.
`GET /v1/webhook-endpoints/{id}/deliveries`	Lista as entregas de um endpoint.
`POST /v1/webhook-deliveries/{id}/redeliver`	Envia uma entrega novamente.

Erros específicos dos webhooks, além dos gerais:

Status	`detail`	Significado
422	`{"code": "invalid_url", "message": "…"}`	A URL não é HTTPS, não tem host, não resolve ou aponta para um endereço privado. `message` diz qual.
422	`"endpoint_limit_reached"`	A organização já tem 10 endpoints. Exclua um primeiro.
422	mensagens por campo	Por exemplo um tipo de evento desconhecido, ou `*` misturado com outros tipos.
404	`"not_found"`	Nenhum endpoint ou entrega com esse id na sua organização.
409	`"endpoint_disabled"`	Você tentou enviar uma entrega novamente enquanto o endpoint dela está desligado.

Estas chamadas contam para o seu limite de uso como qualquer outra solicitação à API. Os eventos que a Ciarem envia para você não contam.

Solução de problemas

Problema	O que conferir
Nenhum evento chega	O endpoint está ativado? Ele está inscrito no evento que você espera? Envie um evento de teste: o resultado mostra exatamente o que o seu servidor respondeu. Confira se o seu plano inclui webhooks.
O teste funciona mas os eventos reais não	O endpoint provavelmente não está inscrito nesse tipo de evento. Abra-o e revise Eventos a enviar.
”Esta URL não pode ser usada”	A URL deve ser `https://` e resolver para um endereço público. Hostnames internos e `localhost` são recusados. Use um túnel para desenvolvimento local.
As entregas falham com um `301` ou `302`	Seu servidor redireciona, muitas vezes de uma URL sem barra final para uma com ela, ou de um domínio sem `www` para um com `www`. Cadastre a URL final.
As entregas falham com `401` ou `403`	Algo na frente do seu servidor (um firewall, uma proteção contra bots ou uma tela de login) bloqueia a solicitação. Permita solicitações `POST` para esse caminho. Você pode reconhecer a Ciarem pelo user agent `Ciarem-Webhooks/1.0`, mas confie na assinatura, não no user agent, para a segurança.
As entregas falham com um timeout	Seu handler leva mais de 10 segundos. Responda `200` primeiro e faça o trabalho em segundo plano.
As entregas falham com um erro de TLS ou de certificado	Seu certificado está vencido, é autoassinado ou foi emitido para outro hostname.
A assinatura não bate	Veja Quando a assinatura falha.
O mesmo evento chega duas vezes	Esperado de vez em quando. Remova duplicados pelo `id` do evento. Se acontece com todos os eventos, confira se dois endpoints apontam para a mesma URL.
`contact.updated` chega várias vezes para uma única edição	Cada propriedade personalizada que muda envia seu próprio evento, e as mudanças de etapa e de proprietário enviam os delas. Veja o catálogo de eventos.
Um endpoint mostra “Desativado por falhas repetidas”	Ele falhou em todas as entregas por 3 dias. Corrija a causa e depois clique em Ativar.
Uma entrega não aparece no registro	O registro guarda 30 dias. Os eventos de teste nunca são registrados.

Primeiros passos

Canais

Seu agente de IA

Usando a Ciarem

Integrações

App móvel

Faturamento

API para desenvolvedores

Entregas e novas tentativas

O que conta como entregue

Novas tentativas

Status das entregas

Quando um endpoint continua falhando

Pausar um endpoint por conta própria

Se o seu plano mudar

Duplicados e ordem

O registro de entregas

Enviar uma entrega novamente

Recuperar o atraso depois de uma queda

Gerenciar endpoints com a API

Solução de problemas

​O que conta como entregue

​Novas tentativas

​Status das entregas

​Quando um endpoint continua falhando

​Pausar um endpoint por conta própria

​Se o seu plano mudar

​Duplicados e ordem

​O registro de entregas

​Enviar uma entrega novamente

​Recuperar o atraso depois de uma queda

​Gerenciar endpoints com a API

​Solução de problemas

O que conta como entregue

Novas tentativas

Status das entregas

Quando um endpoint continua falhando

Pausar um endpoint por conta própria

Se o seu plano mudar

Duplicados e ordem

O registro de entregas

Enviar uma entrega novamente

Recuperar o atraso depois de uma queda

Gerenciar endpoints com a API

Solução de problemas