Guias › Integração
Webhooks
Rode um agente quando outro sistema chamar um endereço, sem chave de API e sem esperar a resposta.
Um gatilho do tipo webhook dá ao agente um endereço próprio. Qualquer sistema que consiga fazer um POST roda o agente: um formulário do site, o CRM, o Stripe, o GitHub, um job agendado. O corpo da requisição vira o contexto da tarefa.
1. Crie o gatilho#
Escolha uma das formas:
- Na tela: abra o agente, vá em Gatilhos › Adicionar gatilho › Webhook, dê um nome e escreva o que o agente deve fazer.
- Na CLI:
doublex triggers create agt_8f3a2b1c9d0e --name "Novo lead do site" --webhook \
--prompt "Chegou um lead: {{nome}} ({{email}}). Pesquise a empresa {{empresa}} e mande um resumo no Slack do comercial."- Na API:
POST /api/triggerscom"type": "webhook"(veja Gatilhos).
A resposta traz o endereço e o segredo do webhook:
trg_4c1e9a7b2d5f
Endereço do webhook: https://doublex.ai/api/webhooks/trg_4c1e9a7b2d5f
Envie o segredo no cabeçalho x-webhook-secret: 3f9a…c21e2. Chame o endereço#
Mande o segredo no cabeçalho x-webhook-secret:
curl -X POST https://doublex.ai/api/webhooks/trg_4c1e9a7b2d5f \
-H "x-webhook-secret: $WEBHOOK_SECRET" \
-H "Content-Type: application/json" \
-d '{"nome": "Ana Souza", "email": "[email protected]", "empresa": "Empresa SA"}'{ "accepted": true }O agente começa na hora, em segundo plano. A resposta 202 não traz o resultado: acompanhe a execução na tela Tarefas (origem Webhook) ou com doublex sessions list --agent <id>. Se você precisa do resultado em outro sistema, peça no prompt para o agente entregar por um conector (Slack, e-mail, planilha, banco de dados).
Como o corpo chega ao agente#
| Corpo | O que o agente recebe |
|---|---|
JSON, e o prompt cita campos como {{email}} ou {{cliente.nome}} | O prompt com os campos preenchidos. {{__RAW_JSON__}} coloca o JSON inteiro. |
| JSON, e o prompt não cita nenhum campo | O prompt, seguido dos dados recebidos em JSON. |
| Texto, formulário ou outro formato | O prompt, seguido do texto recebido. |
Gatilho com Enviar o JSON bruto em vez de um prompt ligado (passRawData) | Só o JSON recebido, sem prompt. |
O corpo pode ter até 200.000 caracteres; o que passar disso é cortado.
Respostas#
| Status | Quando |
|---|---|
202 | Aceito. O agente está rodando. |
404 | Gatilho inexistente, segredo errado ou gatilho que não é webhook. A resposta é a mesma nos três casos, de propósito. |
409 | O gatilho está desligado, ou a execução anterior ainda não terminou (tente de novo em instantes). |
402 | A empresa está sem plano ativo (plan_required) ou sem créditos (no_credits), ou o agente atingiu o orçamento do mês (agent_budget). O evento não roda; reenvie depois. |
503 | O agente não tem um modelo de IA disponível. |
Quem paga e com que conta#
- O agente roda com a conta de quem criou o gatilho: usa os conectores e as permissões dessa pessoa.
- O consumo sai dos créditos da organização. Se os créditos acabarem, o webhook ainda responde
202, mas a tarefa falha e aparece como Falhou em Tarefas.
Exemplos de uso#
- Formulário do site → qualificação de lead: o formulário chama o webhook, e o agente pesquisa a empresa, registra no CRM e avisa o vendedor.
- Pagamento confirmado → onboarding: o provedor de pagamentos chama o webhook, e o agente manda o e-mail de boas-vindas e cria a pasta do cliente no Drive.
- Erro em produção → triagem: o monitoramento chama o webhook, e o agente lê o erro, procura o histórico no Brain e abre um resumo para o time.