How to configure webhooks in Toast for Unified

August 12, 2026

Toast pushes restaurant events to a partner webhook URL. Toast does not expose a programmatic subscribe API for these subscriptions — they are created in the Toast Developer Portal and/or with the Toast Integrations team. Point that URL at Unified so your Unified webhooks receive native events.

Official Toast docs:

• Webhook basics
• Subscriptions
• Message signing
• Webhooks reference

Prerequisites

1. A Toast partner / developer account with access to the Toast Developer Portal.
2. At least one Unified Toast connection for the restaurant (auth must include the restaurant GUID in other_auth_info[3] / Toast-Restaurant-External-ID).
3. One or more Unified native webhooks on that connection for the object types you care about (created in the Unified dashboard or via the Unified webhooks API). Creating the Unified webhook stores a toast-{restaurantGuid} subscription marker so inbound Toast deliveries can be matched.

1. Get your Unified workspace webhook URL

Unified receives Toast deliveries on the workspace webhook endpoint for the toast integration:

https://{api-host}/webhook/workspace/toast?workspace_id={your_workspace_id}

Replace:

• {api-host} — your Unified API host for the region (US / EU / AU), e.g. api.unified.to
• {your_workspace_id} — the Unified workspace that owns the Toast connection(s)

Use the same URL for every Toast event category you subscribe to. Unified fans out each delivery to the matching native webhooks for that restaurant.

2. Create Toast webhook subscriptions

In the Toast Developer Portal → Webhooks:

1. Open Add webhook (or ask Toast Integrations to create the subscription if portal create is not enabled for your partner account).
2. Set Webhook URL to the Unified URL from step 1.
3. Choose an Event category (one subscription per category; each category gets its own secret key).
4. Save the subscription and copy the secret key shown on the subscription details page.

Repeat for each category you need (see mapping below). Toast environments (sandbox vs production) have separate subscriptions and secrets.

To remove a subscription later, contact Toast Integrations or delete it in the Developer Portal — Unified unsubscribe only clears local matching cache; it cannot delete Toast-side subscriptions.

3. (Recommended) Store signing secrets on the connection

Toast signs each POST with HMAC-SHA256 and sends Toast-Signature (Base64). The secret is per event category.

If you store secrets on the Toast connection auth metadata, Unified verifies the signature before dispatching:

{
  "toast_webhook_secrets": {
    "stock": "<secret-from-stock-subscription>",
    "menus": "<secret-from-menus-subscription>",
    "partner": "<secret-from-partner-subscription>",
    "order_updated": "<secret-from-orders-subscription>",
    "channel_order_updated": "<secret-from-channel-orders-subscription>",
    "restaurant_availability": "<secret-from-availability-subscription>"
  }
}

Put this object under the connection's auth.meta (or merge into existing auth.meta). If a category has no secret configured, Unified accepts the delivery without signature checks (Toast treats signing as recommended, not required).

4. Event category → Unified object mapping

5. Create matching Unified native webhooks

For each row you care about in the table above:

1. Create a Unified webhook with webhook_type: native, the Toast connection_id, the object type, and the event (created / updated / deleted).
2. Point the webhook's delivery URL at your application (Unified will POST converted unified objects there when Toast fires).
3. Ensure the Toast connection's restaurant GUID matches the location that will emit events.

Troubleshooting