DialStack Webhook Protocol (1.0.0)

When an AI agent with scheduling enabled needs customer or calendar data, DialStack sends a request to the base URL configured on that agent. Your system processes the request and returns a response that DialStack hands to the agent as is.

These are synchronous request/response calls, separate from the event webhooks you configure through the Webhook Endpoints API.

Scheduling is configured per AI agent. Set scheduling.webhook_url when you create or update the agent (POST /v1/ai-agents or POST /v1/ai-agents/{ai_agent_id}). Scheduling is on for an agent while scheduling.webhook_url is set.

DialStack appends the operation path to that base URL:

• {webhook_url}/customers/lookup
• {webhook_url}/availability/search
• {webhook_url}/bookings

All requests include these headers:

Requests are signed with the secret of the agent's voice app. Read it with GET /v1/voice-apps/{voice_app_id}, using the agent's voice_app. If you rotate the voice app's secret, the agent signs with the new one from the next call.

The X-DialStack-Signature header contains a timestamp and signature:

X-DialStack-Signature: t=1697634600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

To verify the signature:

1. Extract the timestamp (t) and signature (v1) from the header
2. Concatenate: {timestamp}.{request_body}
3. Compute: HMAC-SHA256(secret, concatenated_string)
4. Compare the computed signature with v1 (use timing-safe comparison)
5. Reject requests where the timestamp is older than 5 minutes

• Return 2xx with a JSON object. The agent reads the object you return as is, so the response schemas below are the shapes it understands best, and any extra fields are available to it in the conversation.
• DialStack waits up to 10 seconds for your response.
• A timeout, an unreachable URL, or a non-2xx status is reported to the agent as a failed request, with the status code but not your response body.

Some platforms have a single scheduling URL and secret that DialStack set up on their platform, rather than a URL on each AI agent. Requests for that setup differ from the per-agent requests described above:

• They are sent to the platform's scheduling URL and signed with the platform's scheduling secret.
• Only /availability/search and /bookings are sent; there is no customer lookup.
• DialStack waits up to 30 seconds for a response, and returns your status code and response body to the requester unchanged.
• Bodies carry account as well as account_id (both the same value).
• The availability range and the booking fields, including customer.email, are passed through as the requester supplied them, and idempotency_key is the requester's Idempotency-Key.

Operations your system implements to receive scheduling requests from DialStack.

DialStack calls them when an AI agent needs to look up a customer, search for availability, or create a booking. Your system processes the request and returns a response.