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.

Veyra Docs TeamUpdated 1 min readVersion 3 · History

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

HTTP
POST https://agents.example.com/veyra/wake
Content-Type: application/json
Authorization: Bearer <your shared token>
JSON
{
  "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.

AgentsOutboundWebhooks