Tools and Webhooks - Aywa Runtime Docs

Server cascade

Webhook targets are resolved from the most specific surface to the broadest fallback so migrated assistant, phone number, and account-level behaviors can continue to work.

Resolution order

tool server
assistant server
assistant serverUrl
phone-number server
phone-number serverUrl
account webhook endpoint

Webhook envelope

Server events are emitted with a stable { "message": ... } envelope. The runtime preserves compatibility fields for older integrations where possible.

Envelope

{
  "message": {
    "type": "status-update",
    "call": {},
    "timestamp": "2026-05-31T00:00:00.000Z"
  }
}

Supported event families

Lifecycle

assistant-request, status-update, end-of-call-report, and conversation-update.

Speech

speech-update, transcript, assistant.speechStarted, and user-interrupted.

Tools

tool-calls, knowledge-base-request, voice-request, and call.endpointing.request.

Telephony

transfer-update, transfer-destination-request, and phone-call-control.

Durable outbox

The runtime writes webhook jobs before dispatch. Attempts record target, status code, latency, event type, attempt count, and next retry metadata.

GET/logs/webhooksInspect jobs and attempts.

GET/logs/webhooks/:idInspect one job or attempt row.

POST/logs/webhooks/:id/replayReplay a stored attempt against the current target.

POST/logs/webhooks/jobs/:id/retryRequeue a failed or skipped durable job.

API request guardrails

Native apiRequest tools are checked before outbound traffic leaves the runtime.

Allowed schemes

Only http and https URLs are accepted.

No URL credentials

Embedded credentials in URLs are rejected.

Private network block

Private, link-local, and reserved IP ranges are blocked by default.

Host allowlists

Model-provided URLs require explicit TOOL_API_REQUEST_ALLOWED_HOSTS.

Header safety

Dynamic sensitive headers such as auth, cookies, and API-key headers are dropped.

Production gate

Private network escape hatches are rejected in production mode.

External actions run through a controlled webhook boundary.