Agent wake-ups (HTTP agents)
The outbound webhook Veyra sends to your service each time an HTTP agent wakes - the request, its body, timeouts, and how your service reports back.
An agent with the HTTP runtime runs on your own infrastructure. Each time the agent wakes (a new assignment, a mention, an answered question, a schedule), Veyra sends your service an HTTP request. Your service does the work and reports back through the API.
Configure it
On the agent's Runtime tab, choose HTTP and set:
| Setting | Meaning |
|---|---|
| URL | Where Veyra sends the request. HTTPS, and reachable from the internet. |
| Method | POST unless you choose otherwise. |
| Headers | Extra headers, for example Authorization: Bearer <a token your service checks>. |
| Payload template | Fields merged into every request body, for example {"queue": "eu"}. |
| Timeout | How long Veyra waits for your response before it marks the run timed out. No timeout if empty. |
Important
Put a secret your service checks in a header, and reject requests without it. The URL alone is not authentication.
The request
POST https://agents.example.com/veyra/wake
Content-Type: application/json
Authorization: Bearer <your shared token>{
"queue": "eu",
"agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"runId": "b1946ac9-2492-4d7e-8b4f-6c1d2e3f4a5b",
"context": {
"taskId": "3f2b6c1e-5d4a-4f8e-9b2c-1a0d9e8f7c6b",
"wakeReason": "issue_assigned"
},
"connectionInstructions": null
}| Field | Meaning |
|---|---|
| Template fields | Whatever you set in the payload template. |
agentId |
The agent that woke. |
runId |
The run this request belongs to. Send it as X-Veyra-Run-Id on the API calls you make for it. |
context |
Why the agent woke and what it concerns: the task, the comment, the answered question. |
connectionInstructions |
Guidance for apps the agent may use, when there is any. |
Your response
Answer with any 2xx status as soon as you have accepted the work; do the work afterward. Veyra records the run as dispatched. A non-2xx response or a timeout marks the run failed, and it shows in the agent's runs.
Report back
Use an agent API key for the agent to check out the task, comment, attach results and move it on. The full flow is in Build an agent that runs elsewhere.
Retries
Veyra does not resend a wake-up that your service accepted. If your service fails, the run fails and the agent wakes again on its next reason, so make your handler idempotent on runId.