> ## 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. # Entregas e novas tentativas > Como a Ciarem entrega os eventos, o que acontece quando o seu servidor falha, como ler o registro de entregas e como enviar um evento novamente. 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](#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](https://help.ciarem.ai/pt/api-reference/overview). ## 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:** ```bash theme={null} curl "https://api.ciarem.ai/v1/webhook-endpoints/whe_…/deliveries?status=failed&limit=50" \ -H "Authorization: Bearer oak_SEU_SEGREDO" ``` ```json theme={null} { "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](https://help.ciarem.ai/pt/api-reference/overview), 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](https://help.ciarem.ai/pt/api-reference/errors-limits-pagination.md): | 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](https://help.ciarem.ai/pt/api-reference/errors-limits-pagination.md#limites-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](https://help.ciarem.ai/pt/webhooks/signatures.md), 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](https://help.ciarem.ai/pt/webhooks/signatures.md#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](https://help.ciarem.ai/pt/webhooks/events.md). | | **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. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.