Webhooks: receber e enviar#

Webhook é o caminho pelo qual um sistema de fora avisa o Doot de que algo aconteceu — uma mensagem chegou, um pagamento foi confirmado, um cadastro mudou. Sem eles, o Doot precisaria ficar perguntando o tempo todo, o que é lento e caro.

Os endereços que o Doot recebe#

Os quatro primeiros são de canal: é por eles que as mensagens dos clientes entram. Se um deles não estiver alcançável, as mensagens daquele canal não chegam — e não há erro na tela do atendente, porque do ponto de vista do painel não houve mensagem nenhuma.

Estes endereços não usam a autenticação normal#

Eles não exigem o login do painel. Não podem: quem chama é a Meta, o Telegram, a Twilio — sistemas que não têm usuário no seu Doot.

O que os protege é a verificação de assinatura do provedor: cada requisição vem assinada, e o Doot confere essa assinatura antes de aceitar.

Isso tem duas consequências práticas:

• Esses endereços precisam estar abertos à internet. Não os bloqueie no firewall junto com o resto — veja Firewall e redes permitidas.
• O segredo de assinatura é o que os protege. Se ele vazar, alguém pode forjar eventos. Trate-o como senha.

Requisitos de publicação#

Os provedores exigem HTTPS com certificado válido e reconhecido. Certificado autoassinado é recusado, e a recusa costuma aparecer como "não consegui validar o webhook" no painel deles — sem dizer que o problema é o certificado.

Veja Certificado SSL.

Como fazer#

1. Publique o servidor com HTTPS válido.
2. No painel do provedor, cadastre o endereço correspondente.
3. Guarde o token de verificação, quando houver: é ele que o provedor usa para confirmar o endereço.
4. Assine os eventos que você quer receber — no caso da Meta, os de mensagem.
5. Mande uma mensagem de teste e confirme que ela chega à fila.

Receber eventos do seu ERP#

O endereço de webhook do ERP permite que o seu sistema avise o Doot de mudanças — um pagamento confirmado, um contrato ativado, uma ordem de serviço concluída.

O uso mais valioso é evitar mensagem errada: um cliente que acabou de pagar não deveria receber a cobrança agendada para daqui a duas horas.

CONFERIR: formato do corpo e método de autenticação aceitos em 7 nesta instalação

Se algo der errado#

O provedor não valida o webhook. Certificado inválido, endereço inacessível de fora, ou token de verificação diferente do configurado.

Mensagens param de chegar de um canal. O webhook parou de ser entregue. Confira o painel do provedor: ele costuma mostrar as últimas entregas e os erros.

Chega mensagem de um canal e não de outro. Cada canal tem a sua assinatura de eventos. Confira uma a uma.

O webhook funciona e depois para depois de renovar o certificado. Certificado renovado com cadeia incompleta é aceito por navegador e recusado por servidor. Confira a cadeia completa.

Você suspeita de evento forjado. Confira o segredo de assinatura e troque-o. Depois veja o que entrou no período em Auditoria de acessos.