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çohttpsacessí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.testdescription: 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 entregadelivered: seu servidor respondeu com 2xxfailed: a última tentativa falhou, e haverá outraexhausted: 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.deactivatedvai 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
idde um endereço comowebhook_endpoint_id, veja Requisições longas em segundo plano.