Surfaces
Webhooks
A webhook lets another program start an agent run by sending an HTTP request to a URL that Adapt gives you, signed with a secret.
Use one when a system you run, such as a ticketing tool, a CI job, or a script, should hand work to an agent. The request's body becomes the agent's input, and the agent follows the instructions of the automation the webhook belongs to. The answer stays in Adapt; it isn't sent back to the program that called.
Create a webhook
Creating a webhook needs permission to edit the agent, and the owner or admin role, since it adds a connection to the workspace.
- Open Agents, pick the agent, and on its Automations tab choose Create from scratch.
- Name the automation and set When to When something happens.
- Under Connected surface, choose Create webhook.
- Write the instructions under Does: what the agent should do with each request.
- Choose Turn on.
Adapt then shows the Webhook URL and the Secret. Copy the secret now: it isn't shown again. The webhook counts toward the agent's 16 surfaces, including Web chat.
Send a request
Send a POST to the webhook URL with the secret as a Bearer token. The body can be any UTF-8 text, JSON included:
curl -X POST "$WEBHOOK_URL" \
-H "Authorization: Bearer $WEBHOOK_SECRET" \
-H "Content-Type: application/json" \
--data '{"ticketId": 123, "message": "New support ticket"}'
Adapt answers before the agent runs:
202with{"received": true, "id": "<delivery ID>"}: accepted. The run starts in the background.401: the secret is missing or wrong.400: the body contains a NUL character.413: the body is longer than 32,000 characters.404: the webhook doesn't exist, or its connection is paused.
A 202 means the request was accepted, not that a run happened. A run starts only when the agent, the webhook, and an automation on it that's turned on are all available.
What the agent receives
Each request starts a new conversation. The agent gets the automation's instructions and the request body. It's told the body is external data, not instructions, and not proof of who sent it.
Webhook runs act as no one. They use the agent's own capabilities, without any member's personal connections or permissions, and nothing in the body can make a run act as a member. Choose the agent's connections with that in mind: anyone holding the secret can start runs with them.
Results appear in the automation's run history on the agent's Automations tab.
Retries and duplicates
Adapt gives every request a new delivery ID, so each request starts its own run, including a retry of a request that already succeeded. The Idempotency-Key header is ignored. If your program retries after a timeout, the agent may do the work twice; make the instructions safe to repeat, or retry only when you know the first request failed.
Use one webhook for several automations
A webhook stays attached to the agent after you create it. Other automations on the same agent can pick it under Connected surface, and each one that's turned on runs for every request. Deleting an automation leaves the webhook in place; requests start no runs until an automation that's turned on uses it.
Pause, replace the secret, or remove
Open the agent's Settings tab and select the webhook under Where it answers:
- Pause turns the webhook off. Requests get
404and start no runs; automations that use it keep their settings. - Replace the secret by entering a new one and saving. The old secret stops working immediately.
- Remove detaches the webhook from the agent and deletes the automations that use it.
Limits
- Body: up to 32,000 characters of UTF-8 text, with no NUL characters.
- Secret: 32–256 characters, using letters, digits, and
-._~+/, optionally ending in=padding. Adapt generates a 43-character secret. - Authentication:
Authorization: Bearer <secret>only.