Webhooks de saída

​

Configurando um webhook

​

Tipos de eventos

​

Formato do pedido

POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella-Webhooks/1
X-Flowella-Signature: <hex digest>

{
  "event": "message.delivered",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "...event-specific fields..." }
}

​

Verificação de assinaturas

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

​

Respostas, tentativas e tempos limite

• Timeout: O Flowella aguarda até 10 segundos para que o seu endpoint responda.
• Success: qualquer resposta do 2xx é tratada como uma entrega bem sucedida.
• Tentativas**: as entregas falhadas são repetidas até 3 tentativas com backoff.
• Desativação automática**: se um webhook acumular 10 falhas consecutivas, o Flowella desactiva-o. Terá de o reativar a partir de Configurações → Webhooks depois de corrigir o seu ponto final.

​

Idempotência

• Use o data.id do evento (ou uma chave derivada como event + data.messageId) como uma chave de idempotência.
• Mantenha uma cache de curta duração das chaves processadas (algumas horas são suficientes para novas tentativas).
• Tratar os duplicados como no-ops.

​

Listando e gerenciando entregas

• Carimbo de data/hora
• Tipo de evento
• Status da resposta
• Um corpo de resposta truncado (até ~1 KB) para depuração

​

Desenvolvimento local

​

Relacionado