Skip to main content
API docs by Redocly

DialStack Webhook Protocol (1.0.0)

Download OpenAPI specification:Download

DialStack Support: support@dialstack.ai URL: https://docs.dialstack.ai

Reference documentation for the webhook protocol that platforms implement to receive appointment requests from DialStack.

Overview

When DialStack's voice AI searches for availability or creates a booking, DialStack sends webhook requests to your platform's configured webhook_url. Your platform processes the request and returns a response that DialStack relays back to the voice AI.

Configuration

Configure webhooks on your platform record:

  • webhook_url: Base URL for webhook endpoints (e.g., https://api.yourplatform.com/dialstack)
  • webhook_secret: Shared secret for signature verification

DialStack appends the endpoint path to your base URL:

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

Request Headers

All webhook requests include these headers:

Header Description
Content-Type Always application/json
X-DialStack-Signature HMAC-SHA256 signature for verification
X-DialStack-Account-Id The account ID for this request

Signature Verification

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(webhook_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

Timeouts

  • DialStack waits up to 30 seconds for your webhook response
  • Design your endpoints to respond quickly; defer heavy processing if needed

Webhooks

Webhook endpoints that your platform implements to receive scheduling requests from DialStack.

These endpoints are called by DialStack when the voice AI needs to look up a customer, search for availability, or create a booking. Your platform processes the request and returns a response.

Lookup Customer

DialStack sends this request at the start of every call to determine if the caller is a new or existing customer.

Your platform should look up the caller by phone number and return their profile if found. Include upcoming appointment information if available — the voice AI uses this for context during the call.

Authorizations:
SignatureAuth
header Parameters
X-DialStack-Account-Id
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

The DialStack account ID for this request

Request Body schema: application/json
required
account_id
required
string

The account ID (same as X-DialStack-Account-Id header)

required
object

Responses

Response Schema: application/json
found
required
boolean

Whether a matching customer record was found

object

Customer details (present only when found is true)

Request samples

Content type
application/json
{
  • "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "customer": {
    }
}

Response samples

Content type
application/json
Example
{
  • "found": true,
  • "customer": {
    }
}

Search Availability

DialStack sends this request when the voice AI needs to find available appointment slots.

Your platform should query your booking system and return matching availability.

Authorizations:
SignatureAuth
header Parameters
X-DialStack-Account-Id
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

The DialStack account ID for this request

Request Body schema: application/json
required
account_id
required
string

The account ID (same as X-DialStack-Account-Id header)

required
object (AvailabilityQuery)

Responses

Response Schema: application/json
required
Array of objects (Availability)

List of available appointment slots

Array
start_at
required
string <date-time>

Slot start time (ISO 8601)

duration_minutes
required
integer >= 1

Slot duration in minutes

Request samples

Content type
application/json
{
  • "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "query": {
    }
}

Response samples

Content type
application/json
Example
{
  • "availabilities": [
    ]
}

Create Booking

DialStack sends this request when the voice AI needs to book an appointment.

Your platform should:

  1. Check the idempotency_key - if you've seen it before, return the original response
  2. Verify the slot is still available
  3. Create the booking in your system
  4. Return the booking confirmation

Idempotency: The idempotency_key prevents duplicate bookings. Store it when processing a booking, and if the same key arrives again, return the original booking response. Keys can be safely expired after 24 hours.

Authorizations:
SignatureAuth
header Parameters
X-DialStack-Account-Id
required
string
Example: acct_01h2xcejqtf2nbrexx3vqjhp41

The DialStack account ID for this request

Request Body schema: application/json
required
account_id
required
string

The account ID (same as X-DialStack-Account-Id header)

idempotency_key
required
string

Unique key to prevent duplicate bookings. If you receive the same key again, return the original booking response. Keys can be safely expired after 24 hours.

required
object (BookingRequest)

Responses

Response Schema: application/json
required
object (Booking)
id
required
string

Your platform's booking ID

status
required
string
Enum: "confirmed" "pending"

Booking status

start_at
required
string <date-time>

Confirmed appointment start time

end_at
required
string <date-time>

Confirmed appointment end time

object
object

Appointment location details

notes
string

Additional booking information such as assigned provider

created_at
string <date-time>

When the booking was created

Request samples

Content type
application/json
{
  • "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  • "idempotency_key": "booking-req-123456",
  • "booking": {
    }
}

Response samples

Content type
application/json
{
  • "booking": {
    }
}