Avisamos quando algo termina.
O FlowModels chama o seu endereço quando uma execução em segundo plano termina, um valor de alerta é atingido ou um destino falha. Toda entrega é assinada, e as que falham são repetidas.
Cinco tentativas, depois para.
Se o seu servidor não responder em 10 segundos ou não responder com um status 2xx, o FlowModels tenta de novo em intervalos fixos. A cada intervalo somam-se até 30 segundos aleatórios, para que as repetições não cheguem todas ao mesmo tempo.
- Tentativa 1 imediata
- Tentativa 2 +60 s após cerca de 1 minuto
- Tentativa 3 +300 s após cerca de 6 minutos
- Tentativa 4 +900 s após cerca de 21 minutos
- Tentativa 5 +3.600 s após cerca de 81 minutos
Depois da quinta tentativa sem sucesso, a entrega fica como exhausted. Se cinco entregas falharem em sequência, o FlowModels desliga o destino, avisa você por e-mail e envia webhook_endpoint.deactivated para os seus outros destinos.
Você vê cada tentativa no histórico de entregas: GET /v1/webhook_endpoints/{uuid}/deliveries, com os status pending, delivered, failed e exhausted.
Oito eventos.
Ao criar um destino, você escolhe pelo menos um. Cada equipe pode ter até dez destinos.
| Evento | É disparado quando |
|---|---|
response.completed |
Uma execução em segundo plano terminou |
response.failed |
Uma execução em segundo plano falhou |
response.cancelled |
Uma execução em segundo plano foi cancelada |
response.incomplete |
Uma execução em segundo plano terminou incompleta |
credit.threshold |
Um dos seus valores de alerta foi atingido |
credit.topup_failed |
Uma recarga automática falhou |
webhook_endpoint.deactivated |
Um destino foi desligado após falhas repetidas |
webhook.test |
Você disparou a entrega de teste |
Nos quatro eventos response.*, o corpo traz apenas o ID e o status. O resultado você busca com GET /v1/responses/{id}; nenhum conteúdo sai do FlowModels pelo webhook.
Verifique cada assinatura.
Os três cabeçalhos seguem o esquema de Standard Webhooks. A assinatura é um HMAC-SHA256 sobre {webhook-id}.{webhook-timestamp}.{Body}, em Base64 com o prefixo v1,. Use o secret como você o recebeu: como texto, sem decodificar de Base64.
POST /flowmodels/events HTTP/1.1
Host: example.com
Content-Type: application/json
webhook-id: 018f1234-5678-7abc-9def-0123456789ab
webhook-timestamp: 1767225600
webhook-signature: v1,<Base64 de HMAC-SHA256>
{
"id": "018f1234-5678-7abc-9def-0123456789ab",
"type": "response.completed",
"created_at": "2026-11-09T10:15:00+00:00",
"data": {
"id": "018f9abc-1234-7def-8abc-0123456789ab",
"status": "completed"
}
}
import base64, hashlib, hmac, time
def is_valid(body: bytes, headers, secret: str) -> bool:
webhook_id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
# Reject replays: five minutes in either direction.
if abs(time.time() - int(timestamp)) > 300:
return False
signed = f"{webhook_id}.{timestamp}.".encode() + body
digest = hmac.new(secret.encode(), signed, hashlib.sha256).digest()
expected = "v1," + base64.b64encode(digest).decode()
# During a rotation the header carries two signatures.
return any(hmac.compare_digest(expected, candidate)
for candidate in headers["webhook-signature"].split(" "))
Criar e testar um destino.
O secret só aparece na resposta da criação. POST /v1/webhook_endpoints/{uuid}/test coloca uma entrega de teste real na fila e responde com 202.
curl https://api.flowmodels.one/v1/webhook_endpoints \
-H "Authorization: Bearer $FLOWMODELS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/flowmodels/events",
"events": ["response.completed", "credit.threshold"],
"description": "Produção"
}'
Trocar o secret sem interrupção.
POST /v1/webhook_endpoints/{uuid}/rotate_secret retorna um novo secret, uma única vez e somente com uma chave de gerenciamento. Durante 24 horas, o FlowModels assina com o secret antigo e com o novo, e o cabeçalho traz dois valores. Assim você faz a troca sem perder nenhuma entrega.
Somente destinos HTTPS públicos.
O endereço precisa começar com https:// e ter no máximo 2.048 caracteres. Um destino não pode apontar para uma rede interna: o FlowModels verifica isso ao salvar e de novo antes de cada tentativa, conecta-se somente ao endereço verificado e não segue redirecionamentos.