FlowModels

Criar e testar webhooks pela API e trocar o segredo

Publicado em 11. novembro 2026

Normalmente, os endereços de webhook são configurados na interface, veja Configurar webhooks do FlowModels. Se você monta muitos ambientes de forma automatizada, seu deploy também pode fazer isso sozinho pela API. Aqui estão os endpoints e qual chave é necessária para cada coisa.

Qual chave?

  • Criar, listar, alterar, excluir, testar e ler o registro de entregas: chave com Usar IA
  • Trocar o segredo: chave com Gerenciar chaves. Uma chave com Usar IA recebe aqui 403 insufficient_key_scope.

Todos os caminhos começam com https://api.flowmodels.one/v1.

Criar um endereço

curl -X POST https://api.flowmodels.one/v1/webhook_endpoints \
  -H "Authorization: Bearer at_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://portal.example.de/webhooks/flowmodels", "events": ["response.completed", "response.failed", "credit.threshold"], "description": "Portal do cliente Produção"}'
  • url: um endereço https acessível publicamente, com no máximo 2.048 caracteres. Verificamos ao salvar e de novo antes de cada entrega.
  • events: pelo menos um evento desta lista: response.completed, response.failed, response.cancelled, response.incomplete, credit.threshold, credit.topup_failed, webhook_endpoint.deactivated, webhook.test
  • description: opcional, com no máximo 255 caracteres

A resposta contém o id do endereço e, no campo secret, o segredo de assinatura. O segredo só aparece nesta resposta. Salve-o imediatamente no seu gerenciador de segredos. Como verificar entregas com ele está em Verificar a assinatura de webhook: código de exemplo para PHP, Node.js e Python.

Cada equipe pode ter no máximo 10 endereços. O décimo primeiro é recusado com HTTP 400.

Listar, alterar, excluir

Tarefa Chamada
todos os endereços GET /webhook_endpoints
um endereço GET /webhook_endpoints/{id}
alterar PATCH /webhook_endpoints/{id}
excluir DELETE /webhook_endpoints/{id}

As listas são paginadas com limit e after. Essas chamadas nunca retornam um segredo.

Com PATCH, você altera url, events, description e is_active. Com "is_active": false, você pausa um endereço, e com true, coloca-o em operação de novo, por exemplo depois de o desativarmos por erros repetidos.

DELETE remove o endereço junto com o registro de entregas dele. Um ID desconhecido ou de terceiros retorna 404 webhook_endpoint_not_found.

Testar e verificar entregas

POST /webhook_endpoints/{id}/test coloca uma entrega do tipo webhook.test na fila. A resposta chega na hora com status: "pending", e a entrega em si acontece logo depois.

Se ela chegou, você vê com GET /webhook_endpoints/{id}/deliveries. Cada entrada informa event_type, status, o número de attempts, o http_status do seu servidor, failure_kind e os horários. Com ?status=, você filtra por:

  • pending: aguardando a entrega
  • delivered: seu servidor respondeu com 2xx
  • failed: a última tentativa falhou, e haverá outra
  • exhausted: todas as tentativas falharam

Trocar o segredo

curl -X POST https://api.flowmodels.one/v1/webhook_endpoints/{id}/rotate_secret \
  -H "Authorization: Bearer at_sua_chave_de_gerenciamento"

A resposta contém o novo secret, de novo apenas desta vez, e secondary_secret_expires_at. Até esse momento, ou seja, por 24 horas, assinamos cada entrega com os dois segredos. O cabeçalho webhook-signature traz então dois valores. Assim, você pode distribuir o novo segredo com calma em todos os servidores, sem perder nenhuma entrega.

Bom saber

  • O evento webhook_endpoint.deactivated vai para todos os outros endereços ativos da sua equipe, nunca para o que acabou de ser desativado. Por isso, crie um segundo endereço se quiser ser informado sobre desativações.
  • Em tarefas em segundo plano, você pode enviar no início o id de um endereço como webhook_endpoint_id, veja Requisições longas em segundo plano.

Este artigo foi útil?

Voltar para Webhooks, usuários finais e MCP