--- title: "How to configure webhooks in Toast for Unified" img: https://unified.to/images/logo.svg date: 2026-08-12T21:48:00.000Z tag: Guides description: "Toast pushes restaurant events to a partner webhook URL. Toast does not expose a" url: "https://unified.to/blog/how_to_configure_webhooks_in_toast_for_unified" --- # 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](/blog/replacing_polling_with_unified_webhooks_and_virtual_streams) receive native events. Official Toast docs: - [Webhook basics](https://doc.toasttab.com/doc/devguide/apiWebhookBasics.html) - [Subscriptions](https://doc.toasttab.com/doc/devguide/apiSubscriptions.html) - [Message signing](https://doc.toasttab.com/doc/devguide/apiMessageSigning.html) - [Webhooks reference](https://doc.toasttab.com/doc/devguide/apiWebhooksReference.html) ## 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: ```plain text https://{api-host}/webhook/workspace/toast?workspace_id={your_workspace_id} ``` Replace: - `{api-host}` — your [Unified API](/technology) 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: ```json { "toast_webhook_secrets": { "stock": "", "menus": "", "partner": "", "order_updated": "", "channel_order_updated": "", "restaurant_availability": "" } } ``` 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 | Toast event category | Toast event types | Unified object(s) | Unified webhook event | | --------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------- | | Orders (`eventCategory` = `order_updated` or `channel_order_updated`) | `order_updated`, `channel_order_updated` | `accounting_order`, `accounting_salesorder`, `payment_payment` | `updated` | | `stock` | `in_stock`, `out_of_stock`, `low_quantity` | `commerce_inventory` | `updated` | | `menus` | `menus_updated` | `commerce_item`, `commerce_collection` | `updated` (publish signal — re-list catalog) | | `restaurant_availability` / `restaurant_availability_toggle` | `availability_online`, `availability_offline`, `toggle_availability_*` | `commerce_availability` | `updated` | | `partner` | `partner_added`, `partner_updated`, `partner_removed` | `commerce_location`, `hris_location` | `created` / `updated` / `deleted` | ## 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 | Symptom | What to check | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Toast shows failures to the URL | Workspace ID query param; HTTPS; region host | | Toast 2xx but no Unified delivery | Native webhook exists for that object/event; connection restaurant GUID matches `details.restaurantGuid`; subscription marker `toast-{guid}` on webhook meta | | Signature failures | Secret for that **exact** `eventCategory`; secrets differ per category and environment | | Empty menu payloads | Expected — treat as 're-list catalog' | | Partner events never match | Connection must already exist for that `restaurantGuid` |