Saltar para o conteúdo principal
Os Webhooks permitem ao Flowella enviar eventos para os seus próprios sistemas em tempo real - por exemplo, notificar o CRM quando uma mensagem WhatsApp é entregue, ou iniciar um trabalho em segundo plano quando uma sincronização de formulário HubSpot falha. Esta página cobre o ecrã in-app Configurações → Webhooks. Para obter os esquemas de carga útil de cada evento, consulte Referência de Webhooks.

​
Quem pode gerir webhooks

Apenas as funções Proprietário e Administrador podem ver Configurações → Webhooks. Outras funções não têm acesso.

​
Adicionando um ponto de extremidade de webhook

1

Abrir Definições → Webhooks

Na navegação esquerda, vá para Configurações → Webhooks.
2

Clique em Adicionar ponto final

Introduza o URL HTTPS público para o qual o Flowella deve efetuar o POST de eventos. HTTP (sem TLS) não é aceite.
3

Escolher os eventos a subscrever

Escolha um ou mais tipos de eventos - por exemplo, message.delivered, template.approved, flow.sync.failed. A lista completa de eventos encontra-se em Referência de Webhooks. Pode subscrever todos os eventos com uma única caixa de verificação.
4

Copiar o segredo de assinatura

O Flowella mostra o segredo de assinatura uma vez no final do fluxo de criação. Guarde-o num local seguro - irá utilizá-lo para verificar a assinatura HMAC em todos os pedidos recebidos.
5

Enviar um evento de teste

Use o botão Enviar teste para disparar um evento sintético no seu ponto de extremidade. O registo de entrega regista o resultado para que possa confirmar que o seu manipulador está ligado antes de entrar em funcionamento.

​
Assinatura e verificação

Cada pedido de webhook inclui um cabeçalho X-Flowella-Signature com uma assinatura HMAC-SHA256 do corpo do pedido em bruto, calculado com o segredo de assinatura do seu ponto final. Verifique-o antes de confiar na carga útil: 
import crypto from "crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
O pedido também inclui:
  • X-Flowella-Timestamp - o carimbo de data/hora Unix no momento do envio. Rejeitar pedidos em que o carimbo de data/hora esteja mais de 5 minutos no passado ou no futuro para evitar ataques de repetição.
  • X-Flowella-Event - o tipo de evento (por exemplo, message.delivered).
  • X-Flowella-Delivery - um ID de entrega único, útil para deduplicação.

​
Tentativas e retrocesso

Se o ponto de extremidade devolver um código de estado não-2xx (ou esgotar o tempo de espera após 10 segundos), o Flowella tenta novamente com um back-off exponencial:
TentativaAtraso após anterior
1 (inicial)-
230 segundos
32 minutos
410 minutos
51 hora
66 horas
7 (final)24 horas
Após 7 tentativas falhadas, a entrega é marcada como falhada e abandonada. O ponto final não é automaticamente desativado - pode continuar a receber eventos futuros no mesmo ponto final. Se 100 entregas consecutivas falharem, o Flowella pausa automaticamente o ponto final e envia uma notificação WEBHOOK_PAUSED. Retome-a a partir do menu da linha quando tiver resolvido o problema subjacente.

​
Registo de entrega

Cada linha de ponto final expande-se para um registo de entrega que mostra os últimos 7 dias de tentativas:
  • Tipo de evento e ID
  • Estado** - sucesso, falha, nova tentativa
  • Número da tentativa**
  • Código e duração da resposta
  • Corpo da resposta (primeiros 1 KB)
  • Enviado para
Clique em qualquer entrega para ver o pedido completo e a resposta, ou para a entregar manualmente.

​
Gerir pontos finais

A partir do menu de linha do ponto final, pode:
  • Editar - alterar o URL ou as subscrições de eventos. (O segredo de assinatura permanece o mesmo).
  • Rotar segredo - gerar um novo segredo de assinatura. O segredo antigo deixa de funcionar imediatamente, pelo que deve coordenar a alteração com o seu gestor.
  • Pausa** - interrompe temporariamente as entregas sem perder a configuração.
  • Retomar** - voltar a ativar um ponto final em pausa.
  • Eliminar** - remover o ponto final e o seu histórico de entregas.

​
Perguntas comuns

Sim - não há um limite rígido. A maioria das organizações tem de 1 a 3 pontos de extremidade (produção, preparação e um coletor de logs interno). Mantenha a contagem baixa para que os eventos se espalhem de forma previsível.
A API é pull - o seu código pede o estado ao Flowella. Os webhooks são push - o Flowella informa o seu código quando o estado muda. Utilize os webhooks para qualquer coisa que, de outra forma, teria de sondar.
As cargas de webhook incluem IDs de conversação, números de telefone de contacto, conteúdo de mensagens e nomes de modelos. Trate o segredo e o URL do ponto final como sensíveis. Restrinja o seu ponto final a aceitar POST do intervalo de IP do Flowella se a sua infraestrutura o permitir.
Use uma ferramenta de túnel (ngrok, Cloudflare Tunnel) para expor seu ponto de extremidade localhost a um URL HTTPS público e, em seguida, aponte um ponto de extremidade de teste para ele. Não coloque um URL de túnel em seu ponto de extremidade de produção - eles expiram.

​
Relacionado

Referência de webhooks

Tipos de eventos, esquemas de carga útil e cabeçalhos.

Chaves API

A outra metade da integração programática.

Introdução à API

Erros, limites de taxa e paginação.

Eventos de notificação

Os mesmos eventos entregues no feed in-app e no e-mail.