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:
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/triggerswith"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…c21e2. Call the URL#
Send the secret in the x-webhook-secret header:
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"}'{ "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#
| Body | What 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 field | The prompt, followed by the received data as JSON. |
| Text, form data or another format | The 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#
| Status | When |
|---|---|
202 | Accepted. The agent is running. |
404 | The 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. |
409 | The trigger is turned off, or the previous run hasn't finished yet (try again in a moment). |
402 | The 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. |
503 | The 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.