Skip to main content
Webhooks de eventos avisam o sistema da sua empresa quando algo muda nesta conta: um projeto criado, um cliente editado, uma mudança de etapa. Você cadastra a URL, escolhe os eventos e a Olie envia um POST assinado para esse endereço — sem montar uma automação. Esta página cobre o cadastro na interface, o formato do aviso e como o seu servidor confere que o POST veio da Olie. A ação Disparar webhook das automações é outro mecanismo; veja Ações: comunicação, IA e execução.

Onde fica

Em Ajustes → Integrações → API, abra a aba Webhooks. Para ver e gerenciar webhooks, o papel precisa das permissões do grupo Webhooks (visualizar, criar, editar e excluir). Se a aba não aparecer, a funcionalidade ainda não está liberada para a sua empresa, ou o seu papel não tem essas permissões.

Cadastrar um webhook

  1. Clique em Novo webhook.
  2. Informe a URL de destino. Use um endereço público em HTTP ou HTTPS. Endereços internos, de localhost ou de metadata de nuvem são recusados.
  3. Dê um Nome só para você reconhecer o webhook na lista.
  4. Em Quais eventos enviar, escolha Tudo o que acontecer nesta conta ou Só alguns eventos (por objeto ou por evento).
  5. Clique em Criar webhook.
Na criação, a Olie mostra o Secret uma única vez. Copie e guarde no seu servidor. Depois dessa tela ele some. Se precisar de um valor novo, use Trocar secret no menu de ações — o secret antigo deixa de valer na hora. Use Enviar teste para disparar o evento webhook.test e conferir se a URL responde. O histórico aparece na aba Envios.

Histórico e reenvio

Na aba Envios de cada webhook você vê cada tentativa: evento, status (Na fila, Entregue ou Falhou), código HTTP, tempo, payload e resposta do destino. Filtre por status ou por evento. Se um envio falhou, use Reenviar. O ID do evento (event_id) permanece o mesmo; a tentativa nova ganha um id de entrega diferente.

Quando a Olie tenta de novo

O primeiro POST sai assim que o evento é publicado. Se a resposta for transitória — timeout, 5xx, ou 408 / 425 / 429 — a Olie agenda outra tentativa na mesma entrega, até 10 no total. Em 429, se o destino mandar Retry-After, esse intervalo prevalece sobre a tabela abaixo. Redirecionamentos (3xx) e a maioria dos 4xx, inclusive 410, encerram a entrega na hora: não há nova tentativa automática. Se as 10 tentativas falharem, aquela linha de Envios fica Falhou. O próximo evento da conta ainda gera uma entrega nova, enquanto o webhook estiver Ativo. Se o destino falhar em dias em que houve tentativa (até 5 dias assim), a Olie desativa o webhook automaticamente e avisa quem pode editar webhooks. Dia sem envio não conta. Um 2xx zera essa contagem. Corrija a URL e use Ativar de novo.

O que o seu sistema recebe

Cada aviso é um POST JSON. A Olie não segue redirects. O corpo e a assinatura usam exatamente os mesmos bytes.

Cabeçalhos

Corpo

Em exclusão, data traz o último estado do objeto. Em webhook.test, data descreve o próprio webhook.

Conferir a assinatura

O secret não viaja no POST. O seu servidor guarda o secret e valida cada chamada.
  1. Leia X-Olie-Webhook-Timestamp e o corpo bruto da requisição (os mesmos bytes, sem re-serializar o JSON).
  2. Monte a string {timestamp}.{corpo_bruto}.
  3. Calcule HMAC-SHA256 com o secret e compare com o valor de X-Olie-Webhook-Signature depois do prefixo sha256=, em tempo constante.
  4. Rejeite se o timestamp estiver velho demais. Uma tolerância de 5 minutos costuma bastar.
Exemplo em Node.js:
Retry e reenvio são POSTs novos: timestamp novo, X-Olie-Webhook-Delivery novo, event_id igual e HMAC recalculado.

Catálogo de eventos

Estes são os eventos que a entrega atual envia. Na interface, você também pode assinar project.*, customer.*, contact.* ou todos os eventos da conta. Um arraste de etapa pode gerar project.step_moved e project.step_unlinked juntos. Assinaturas amplas (project.* ou todos os eventos) recebem os dois POSTs.

Páginas relacionadas

Integrações

Canais, aplicações, webhooks e a API no mesmo mapa.

Disparar webhook (automação)

Ação de automação com corpo customizado, sem HMAC deste fluxo.