Saltar para o conteúdo principal
A caixa de diálogo New webhook com campos para o nome, o URL do endpoint e o segredo de assinatura, e a lista de eventos a enviar
Um webhook de saída faz com que o Flowella envie um POST HTTP para o seu próprio sistema sempre que ocorre um evento escolhido, por exemplo quando um contacto envia uma mensagem WhatsApp. Esta página mostra como adicionar, testar e gerir endpoints de webhook na aplicação. Para os tipos de eventos, corpos de pedido, cabeçalhos e a forma de verificar assinaturas, consulte a referência de webhooks.

​
Antes de começar

  • Precisa da função Owner ou Admin. As outras funções conseguem ver Webhooks no menu, mas a lista não carrega para elas. Consulte Equipa e funções.
  • Precisa de um URL público que aceite pedidos POST com um corpo JSON e responda com um estado 2xx no prazo de 10 segundos.
  • Escolha um segredo de assinatura com pelo menos 8 caracteres e guarde-o num local onde o seu handler o possa ler. O Flowella utiliza-o para assinar cada pedido e nunca o volta a mostrar depois de o guardar.

​
Adicionar um endpoint de webhook

1

Abra Webhooks

Aceda a Settings e selecione Webhooks no grupo Developer. Abre-se o ecrã Outbound webhooks.
2

Inicie um novo webhook

Selecione Add webhook. Abre-se a caixa de diálogo New webhook.
3

Dê um nome ao endpoint (opcional)

Em Name (optional), introduza até 80 caracteres, por exemplo CRM sync. O nome aparece por cima do URL na lista.
4

Introduza o URL do endpoint

Em Endpoint URL, introduza o endereço completo para onde o Flowella deve enviar os eventos. Tem de cumprir as regras do URL.
5

Introduza o seu segredo de assinatura

Em Signing secret, escreva o segredo que escolheu, com entre 8 e 512 caracteres. O Flowella não gera um por si.
6

Escolha os eventos

Em Events, assinale cada evento que pretende receber. A referência de webhooks explica quando cada um é disparado.
7

Guarde

Selecione Create webhook. O botão permanece indisponível até introduzir um URL, um segredo com pelo menos 8 caracteres e pelo menos um evento. O novo webhook aparece na lista com o estado Active.

​
Regras do URL

O Flowella verifica o URL quando o guarda e novamente antes de cada entrega. O URL tem de:
  • Começar por https:// ou http://. O http:// simples funciona, mas nesse caso o payload circula sem encriptação, por isso utilize https:// fora de testes rápidos.
  • Não conter nome de utilizador nem palavra-passe.
  • Apontar para um endereço público. O Flowella recusa localhost, nomes de anfitrião terminados em .localhost ou .local, e metadata.google.internal. Também recusa nomes de anfitrião que não são resolvidos. Os endereços privados, de loopback, link-local e não especificados também são recusados, quer os introduza diretamente quer um nome de anfitrião aponte para eles. Exemplos: 10.0.0.5, 127.0.0.1, 169.254.169.254, 192.168.1.10 e ::1.
  • Ter no máximo 2.048 caracteres.
Um URL que não cumpra estas regras mostra o erro Webhook URL host is not allowed.

​
Enviar um evento de teste

Utilize um evento de teste para verificar se o seu endpoint recebe e aceita pedidos antes de chegarem eventos reais.
  1. Na lista, selecione o botão … no fim da linha do webhook para abrir o respetivo menu de ações.
  2. Selecione Send test event. Aparece uma confirmação por baixo do URL do webhook.
  3. Abra Delivery log a partir do mesmo menu. Uma linha webhook.test com o Result OK significa que o seu endpoint respondeu com um estado 2xx.
Um evento de teste tem o tipo webhook.test e os data { "test": true, "sentAt": "..." }. O Flowella envia-o independentemente dos eventos que assinalou, e mesmo quando o webhook está inativo. A referência de webhooks mostra o corpo completo.

​
Registo de entregas

Selecione Delivery log no menu de ações de um webhook para ver as suas últimas 50 tentativas de entrega, das mais recentes para as mais antigas. O registo na aplicação não mostra os corpos das respostas e não tem botão para reenviar. Para ler os primeiros 1.024 caracteres do corpo de uma resposta, ou para reenviar um evento, utilize a API de entregas de webhooks.

​
Novas tentativas e intervalo entre tentativas

Uma entrega é bem-sucedida quando o seu endpoint responde com um estado 2xx no prazo de 10 segundos. Caso contrário, o Flowella tenta novamente de imediato: 3 tentativas no total, cerca de 1 segundo após a primeira falha e cerca de 2 segundos após a segunda. Após a terceira tentativa falhada, o Flowella descarta esse evento e não volta a tentar mais tarde. O fluxograma mostra o que acontece a cada evento e quando o Flowella desativa um webhook. Quando 10 eventos seguidos falham todas as tentativas, o Flowella desativa o webhook e o seu estado muda para Inactive. Todos os Owners da organização recebem uma notificação na aplicação com o título “Outbound webhook disabled”, sejam quais forem as suas preferências de notificação. Qualquer entrega bem-sucedida repõe o contador a zero. Enquanto um webhook está inativo, o Flowella não lhe envia eventos e não os guarda para enviar mais tarde. Para recuperar os eventos que perdeu, leia o feed de eventos com GET /v1/events, que guarda os eventos durante 7 dias. Consulte a referência de webhooks.

​
Gerir endpoints

O menu de ações de cada linha tem Edit, Send test event, Delivery log e Delete.

​
Editar um webhook

Selecione Edit para abrir a caixa de diálogo Edit webhook. Pode alterar:
  • Endpoint URL.
  • Events. Pelo menos um tem de continuar assinalado.
  • Webhook active. Desmarque esta opção para parar as entregas durante algum tempo. Os eventos que ocorrem enquanto o webhook está inativo não são enviados mais tarde.
  • New signing secret. Deixe em branco para manter o segredo atual. Um novo segredo tem de ter pelo menos 8 caracteres, caso contrário o Flowella mantém o atual.
Selecione Save para aplicar as alterações.
Um novo segredo guardado na aplicação substitui o antigo de imediato, pelo que os pedidos assinados com o segredo antigo deixam logo de ser aceites. Para mudar de segredo sem perder eventos, rode o segredo através da API. Durante 24 horas após uma rotação, cada pedido inclui também uma assinatura feita com o segredo antigo no cabeçalho X-Flowella-Signature-Previous. Consulte Rodar um segredo de assinatura.
A caixa de diálogo de edição também mostra Name (optional), mas um nome alterado não é guardado. Para mudar o nome de um webhook, utilize PATCH /v1/webhooks/{id} com um name.

​
Reativar um webhook

Depois de o Flowella desativar um webhook, corrija primeiro o problema no seu endpoint. Em seguida:
  1. Selecione Edit, assinale Webhook active e selecione Save.
  2. Selecione Send test event e verifique se o Delivery log mostra OK.
Não salte o teste. Ativar o webhook na aplicação mantém o contador de falhas em 10, pelo que um único evento falhado volta a desativá-lo. Uma entrega bem-sucedida, como um evento de teste aprovado, repõe o contador. A chamada de API POST /v1/webhooks/{id}/reactivate ativa o webhook e repõe o contador num só passo.

​
Eliminar um webhook

Selecione Delete e confirme Delete na caixa de diálogo Delete webhook?. O Flowella remove o endpoint e o respetivo histórico de entregas. Esta ação não pode ser anulada.

​
Resolução de problemas

Introduza um URL de endpoint, um segredo de assinatura com pelo menos 8 caracteres e assinale pelo menos um evento.
O URL não cumpre uma das regras do URL. Verifique se o nome de anfitrião é resolvido publicamente e não aponta para um endereço privado ou local. Para testar no seu próprio computador, exponha-o através de um túnel público e utilize o endereço do túnel.
Só os Owners e Admins podem ver e gerir webhooks. Peça a um Owner ou Admin que configure o webhook por si. As funções não podem ser alteradas na aplicação: consulte Alterar a função de alguém.
Verifique se o webhook está Active e se o evento está assinalado em Events. Alguns eventos só são disparados em determinados casos: por exemplo, os eventos de contacto só são disparados para alterações feitas através da API, e optout.created não é disparado de momento para o primeiro opt-out de um contacto num número. A referência de webhooks lista cada caso. Algumas entregas são ignoradas sem entrada no registo. Isto acontece com eventos maiores do que 256 KB e com entregas para um URL que já não cumpre as regras do URL, por exemplo após uma alteração de DNS.
Verifique a coluna HTTP. Um traço significa que o seu endpoint não respondeu em 10 segundos ou não pôde ser contactado. Responda com um estado 2xx assim que receber o pedido e faça qualquer trabalho demorado em segundo plano.
Calcule a assinatura sobre o corpo bruto do pedido, antes de qualquer análise JSON, utilizando exatamente o segredo que guardou. Consulte Verificar assinaturas.

​
Relacionado

Referência de webhooks

Tipos de eventos, corpos, cabeçalhos e verificação de assinaturas.

Chaves API

Crie a chave de que precisa para gerir webhooks através da API.

Developer hub

Pedidos de API recentes, guias de início rápido e a sandbox da API.

Notificações

Onde aparece o alerta Outbound webhook disabled.
Última modificação em 24 de outubro de 2026