Orbitali Docs

Create a Webhook Agent

Coordinate tool calls and optional per-call prompts through your backend.

A webhook agent sends Orbitali events to one Server URL. Choose this type when your backend handles tool dispatch or supplies instructions for each conversation. If you only need to call existing APIs, consider an HTTP agent.

For call start/end notifications and asynchronous summaries, use organization call lifecycle webhooks. Those work with every agent type and use a separate endpoint configuration and signature protocol.

1. Prepare the handler

Provide a public HTTPS endpoint that accepts POST requests. Configure a signing secret and verify the raw request body before parsing it. Route requests by message.type:

EventYour handler returns
agent:tool-callThe requested action's result as JSON
agent:assistant-request{ "prompt": "...", "greeting": "..." }; greeting is optional

The Webhooks protocol guide includes signature verification and full request/response examples. Its sample handler acknowledges a tool call; replace that acknowledgment with your own action dispatch.

2. Create the agent

In Agents → Create Agent, select Webhook. Configure the Server URL and Server Secret, then saved identity, instructions, and greeting.

For the API, use the complete creation request in API Getting Started, changing agentType to webhook, serverUrl to your endpoint, and serverSecret to your signing secret. Keep the secret in your server configuration and out of source control.

Start with promptType: "static" to use saved instructions. For per-call instructions, use promptType: "dynamic". Your handler must return prompt to agent:assistant-request. Set greetingType: "dynamic" and staticGreeting: null if you also return a dynamic greeting. Dynamic greetings require dynamic prompt mode.

3. Register tools

Use Create a tool to register each function's name, description, and argument schema. Set toolUrl: null: webhook tools use the saved Server URL. The handler receives the function name in message.toolCall.name and its arguments in message.toolCall.arguments.

A saved Server URL is required before adding custom webhook tools. An agent can also use a saved prompt without custom tools; choosing webhook does not require dynamic prompts.

4. Activate and test

Activate using the API walkthrough or dashboard. Start a browser or phone conversation. Verify signatures, the tool name and arguments, and the returned result. For dynamic prompts, also verify the startup event and its response before testing tools.

Inspect Calls & Logs for tool errors and timeouts. Return only the information needed for the conversation, and avoid logging raw caller data. See privacy-safe webhook handling.

On this page