Webhook do Funil

O webhook do funil avisa outro sistema da sua empresa a cada movimentação: oportunidade criada, mudou de etapa, foi ganha, foi perdida. É assim que um sistema externo — de faturamento, de implantação — fica sabendo da venda sem ninguém digitar nada duas vezes.

Cada aviso é enviado para o endereço configurado no funil, em POST, com os dados em JSON.

Configurar o endereço

URL do webhook: o endereço que recebe os avisos. Vazio, o funil não envia nada.

Os botões de segredo e de teste só aparecem depois que o funil é salvo — a tela avisa: "Salve o funil para poder gerar segredo e testar."

Segredo e assinatura

Gerar segredo: cria uma senha que o seu sistema usa para conferir que o aviso veio mesmo da plataforma. Ela aparece uma vez só — "Guarde agora: este segredo não será mostrado de novo."

Trocar segredo: cria um segredo novo na hora, sem pedir confirmação. Daí em diante, as assinaturas usam o segredo novo — atualize o seu sistema.

Com o segredo gerado, cada aviso leva um cabeçalho de assinatura cujo valor começa com sha256=. É o HMAC-SHA256 do corpo recebido, calculado com o segredo como chave. O seu sistema refaz a conta e compara: se bater, o aviso é legítimo. Para ver o nome exato do cabeçalho, use Enviar teste e olhe o que chegou. Sem segredo, os avisos chegam sem assinatura.

Os avisos enviados

O campo evento do JSON diz o que aconteceu:

Excluir uma oportunidade não gera aviso.

O que vai em cada aviso

evento e ocorridoEm, a data e hora.

funil, com número e nome.

oportunidade: número, valor, status (OPEN, WON ou LOST), etapa, contato e responsável.

de e para: a etapa anterior e a nova.

valorAntes e valorDepois.

observacao — no ENCADEADA, o funil e o número da oportunidade criada.

autor: quem fez a movimentação.

O contato vai com nome, número e e-mail. Configure só endereços do seu próprio sistema.

O motivo da perda não vai no aviso.

Testar e acompanhar

Enviar teste: manda um aviso TESTE e mostra se foi entregue. Usa a URL salva — trocou o endereço, salve antes de testar.

Últimas entregas: cada aviso com o evento, a situação (entregue ou falhou), o código de resposta do seu sistema e a hora. Ao lado do título, a quantidade de falhas. Atualizar recarrega a lista.

Reenviar: aparece nos avisos que falharam.

Quando a entrega falha, a plataforma tenta de novo sozinha, com intervalos cada vez maiores. A linha mostra quantas tentativas já foram feitas.

Trocou a URL? O Reenviar e as novas tentativas passam a usar o endereço novo. Os avisos que falharam antes ainda podem chegar: clique em Reenviar em cada um.