DoubleX AgentesDocs

Guides › Integration

Webhooks

Run an agent when another system calls a URL, with no API key and without waiting for the answer.

A webhook trigger gives the agent its own URL. Any system that can make a POST can run the agent: a website form, your CRM, Stripe, GitHub, a scheduled job. The request body becomes the task's context.

1. Create the trigger#

Pick one of these options:

  • In the app: open the agent, go to Triggers › Add trigger › Webhook, give it a name and write what the agent should do.
  • In the CLI:
Terminal
doublex triggers create agt_8f3a2b1c9d0e --name "New website lead" --webhook \
  --prompt "New lead: {{name}} ({{email}}). Research the company {{company}} and send a summary to the sales team's Slack."
  • In the API: POST /api/triggers with "type": "webhook" (see Triggers).

The response includes the webhook URL and secret:

trg_4c1e9a7b2d5f
Webhook address: https://doublex.ai/api/webhooks/trg_4c1e9a7b2d5f
Send the secret in the x-webhook-secret header: 3f9a…c21e

2. Call the URL#

Send the secret in the x-webhook-secret header:

Terminal
curl -X POST https://doublex.ai/api/webhooks/trg_4c1e9a7b2d5f \
  -H "x-webhook-secret: $WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ana Souza", "email": "[email protected]", "company": "Empresa SA"}'
JSON
{ "accepted": true }

The agent starts right away, in the background. The 202 response doesn't include the result: follow the run on the Tasks page (source Webhook) or with doublex sessions list --agent <id>. If you need the result in another system, ask the agent in the prompt to deliver it through a connector (Slack, email, a spreadsheet, a database).

How the body reaches the agent#

BodyWhat the agent receives
JSON, and the prompt references fields like {{email}} or {{customer.name}}The prompt with the fields filled in. {{__RAW_JSON__}} inserts the whole JSON.
JSON, and the prompt doesn't reference any fieldThe prompt, followed by the received data as JSON.
Text, form data or another formatThe prompt, followed by the received text.
Trigger with Send raw JSON instead of a prompt turned on (passRawData)Only the received JSON, with no prompt.

The body can be up to 200,000 characters; anything beyond that is cut off.

Responses#

StatusWhen
202Accepted. The agent is running.
404The trigger doesn't exist, the secret is wrong, or the trigger isn't a webhook. The response is the same in all three cases, on purpose.
409The trigger is turned off, or the previous run hasn't finished yet (try again in a moment).
402The company has no active plan (plan_required) or no credits (no_credits), or the agent reached its monthly budget (agent_budget). The event doesn't run; send it again later.
503The agent has no AI model available.

Who pays, and with which account#

  • The agent runs with the account of whoever created the trigger: it uses that person's connectors and permissions.
  • Usage comes out of the organization's credits. If credits run out, the webhook still responds 202, but the task fails and shows up as Failed in Tasks.

Use cases#

  • Website form → lead qualification: the form calls the webhook, and the agent researches the company, logs it in the CRM and notifies the sales rep.
  • Payment confirmed → onboarding: the payment provider calls the webhook, and the agent sends the welcome email and creates the customer's folder in Drive.
  • Production error → triage: monitoring calls the webhook, and the agent reads the error, searches the Brain for history and posts a summary for the team.