> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Configure webhooks de saída em Definições → Webhooks: URLs de endpoint, segredos de assinatura, subscrições de eventos, novas tentativas e registos de entrega.
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](/pt/api-reference/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
Na navegação esquerda, vá para **Configurações → Webhooks**.
Introduza o URL HTTPS público para o qual o Flowella deve efetuar o POST de eventos. HTTP (sem TLS) não é aceite.
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](/pt/api-reference/webhooks). Pode subscrever todos os eventos com uma única caixa de verificação.
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.
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:
```js Node.js theme={null}
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));
}
```
```python Python theme={null}
import hmac, hashlib
def verify(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
```
```ruby Ruby theme={null}
require "openssl"
def verify(raw_body, signature, secret)
expected = OpenSSL::HMAC.hexdigest("sha256", secret, raw_body)
Rack::Utils.secure_compare(expected, signature)
end
```
```php PHP theme={null}
function verify(string $rawBody, string $signature, string $secret): bool {
$expected = hash_hmac('sha256', $rawBody, $secret);
return hash_equals($expected, $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:
| Tentativa | Atraso após anterior |
| ----------- | -------------------- |
| 1 (inicial) | - |
| 2 | 30 segundos |
| 3 | 2 minutos |
| 4 | 10 minutos |
| 5 | 1 hora |
| 6 | 6 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
Tipos de eventos, esquemas de carga útil e cabeçalhos.
A outra metade da integração programática.
Erros, limites de taxa e paginação.
Os mesmos eventos entregues no feed in-app e no e-mail.