Com webhooks, o FlowModels avisa você sobre eventos por conta própria, sem que sua aplicação precise ficar perguntando. Casos típicos são uma resposta concluída em segundo plano ou um aviso de saldo. Para isso, enviamos uma requisição assinada para um endereço à sua escolha.
Criar um webhook
- No dashboard, abra o item Webhooks.
- Clique em Adicionar webhook.
- Em Endereço, informe a URL do seu receptor. Ela precisa ser acessível por https e não pode apontar para um destino interno.
- Em Eventos, selecione pelo menos um evento.
- Opcional: informe uma Descrição, para saber depois para que serve o endereço.
- Clique em Guardar.
Logo em seguida, mostramos O teu segredo de assinatura. Copie imediatamente e guarde na sua aplicação, porque ele é exibido uma única vez. Feche a janela com Já copiei. Cada equipe pode ter até 10 endereços.
Os eventos
response.completed,response.failed,response.cancelled,response.incomplete: uma resposta iniciada em segundo plano foi concluída, falhou, foi cancelada ou terminou incompleta.credit.threshold: um dos seus limites de aviso foi atingido.credit.topup_failed: uma recarga automática falhou.webhook_endpoint.deactivated: um endereço de webhook foi desativado depois de falhas repetidas.webhook.test: uma entrega de teste disparada por você.
Verificar entregas
Cada entrega traz os cabeçalhos webhook-id, webhook-timestamp e webhook-signature. Com seu segredo de assinatura, sua aplicação verifica que a mensagem veio mesmo de nós e não foi alterada no caminho. Como essa verificação funciona em detalhes está em Verificar a assinatura de webhook.
A lista de webhooks
Na lista, você vê para cada endereço os Eventos, o Estado, as Falhas seguidas e a Última entrega. À direita, em Ações, você encontra:
- Abrir registo de entregas: todas as entregas para esse endereço
- Enviar entrega de teste: envia um evento
webhook.test, ideal depois da configuração - Editar webhook: alterar endereço, eventos e descrição
- Rodar segredo: gerar um novo segredo
- Desativar webhook e Reativar webhook
- Eliminar webhook: remove definitivamente o endereço e o registro de entregas dele

O registro de entregas
O Registo de entregas mostra cada entrega com Hora, Identificador, Evento, Estado, número de Tentativas, o código HTTP do seu servidor e a Conclusão. O registro não mostra o conteúdo transmitido, de propósito.

Se o seu servidor não responder com um código de sucesso, tentamos de novo, com intervalos crescentes de cerca de um minuto até uma hora e até cinco vezes no total. Os estados significam:
- Pendente: a entrega ainda está aguardando.
- Entregue: seu servidor respondeu com sucesso.
- Falhou: a última tentativa deu errado, e haverá outra tentativa.
- Desistido: todas as tentativas falharam.
Trocar o segredo
Clique em Rodar segredo e confirme. Você vê um novo segredo, de novo apenas uma vez. O segredo anterior continua assinando por 24 horas, para que você possa fazer a troca sem perder entregas. Enquanto isso, a lista mostra Segredo anterior válido até …. Quando tiver colocado o novo segredo em todos os lugares, você pode invalidar o antigo imediatamente com Concluir rotação.
Quando algo não funciona
- Desativado, “Desativado automaticamente após várias falhas”: depois de cinco entregas seguidas com falha definitiva, desativamos o endereço e informamos você. Corrija o problema no seu servidor, clique em Reativar webhook e envie uma entrega de teste.
- Máximo atingido: o limite é de 10 endereços. Exclua um endereço de que você não precisa mais.
- O endereço é recusado: verifique se ele começa com
https://e é acessível publicamente.