DoubleX AgentesDocs

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:
Terminal
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/triggers com "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…c21e

2. Chame o endereço#

Mande o segredo no cabeçalho x-webhook-secret:

Terminal
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"}'
JSON
{ "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#

CorpoO 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 campoO prompt, seguido dos dados recebidos em JSON.
Texto, formulário ou outro formatoO 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#

StatusQuando
202Aceito. O agente está rodando.
404Gatilho inexistente, segredo errado ou gatilho que não é webhook. A resposta é a mesma nos três casos, de propósito.
409O gatilho está desligado, ou a execução anterior ainda não terminou (tente de novo em instantes).
402A 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.
503O 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.