Adding a webhook subscription

Use the instructions below to add a new webhook subscription to your Toast integration.

  1. Setup and planning

    Consider how webhook events will update your system 

    How will your system behave when you receive a webhook event? Will you automatically update data in your system? Will you prompt action from a user? Before writing any code, think about how webhook events should trigger updates in your system.

    Decide fallback API polling frequency 

    All Toast webhooks have a fallback API. Your integration should periodically query the fallback API in case you miss a webhook. Before you build your webhook implementation, decide how often you will poll the corresponding fallback API; for example, the partners API corresponds to the partners webhook. Toast support recommends that you poll the partners API periodically (such as once per hour) to ensure that you receive all information in the partners domain, even if you miss a webhook.

    Make a plan for subscription pauses and stops 

    If your webhook endpoint is unavailable or returns a high volume of errors, the Toast platform may pause or stop your subscription until you are able to resolve the issue. You will receive a notification email if your subscription is paused or stopped. If your subscription is stopped, you will need to contact Toast support in order to resume your subscription. For more information, see Back-off support.

    Send your webhook sandbox URL and notification email to Toast 

    Contact Toast support and submit the URL for your webhook subscription in the sandbox environment. When submitting your URL, also include the email address that should receive notifications if your subscription is paused or stopped.

    Test a webhook event 

    To view the structure of a webhook, open the Toast POS app or the Toast administration back-end and perform the action that will trigger the webhook event. Webhook reference documentation describes how to trigger each webhook. After you trigger the webhook event, review the JSON your endpoint receives so you understand the structure and content of the webhook.

  2. Endpoint development

    Build successful response submission 

    When you receive a webhook event that is structured correctly, submit a 2xx response before doing any additional business logic on the event and process events asynchronously. Providing a 2xx response before business logic allows Toast API clients to scale efficiently. You will receive webhooks for all locations connected to your integration and you are responsible for submitting a 2xx response when receiving webhook events for any of these locations. See this page for more information about asynchronous webhook processing.

    Validate idempotence using event GUIDs 

    If your endpoint is unable to receive a webhook event, the Toast platform may try to send the event again. If you received the original webhook and the Toast platform did not recognize that you received it, the retry may result in duplicate webhook information. You can avoid this problem by using the event GUID to ensure idempotence. If two webhooks have the same event GUID, you must treat them as the same webhook event. For more information about webhook retries, see Retry support.

    Validate that you send timely responses 

    Your endpoint should adhere to Toast webhook timeout requirements for the Toast platform to correctly understand whether or not you received the webhook. If your webhook does not adhere to timeout requirements, you may receive unnecessary duplicate webhook events and your subscription may become paused or stopped.

    Review endpoint requirements 

    Review this list of endpoint requirements to ensure that you meet all requirements before going live on your webhook functionality in production.

    Implement message signing 

    By using message signing, you ensure that you only take action on webhooks that were sent by the Toast platform. Using message signing provides an extra layer of security against acting upon webhooks from unknown sources. For more information, see Message signing.

  3. Going live

    Submit production endpoint to Toast 

    When you are ready to take your new webhook subscription live in production, submit your production URL to your Toast contact. Toast support recommends following these deployment practices as you roll out your webhook usage, though you should still return a 200 response to all correctly-structured webhooks you receive from Toast. In addition to your production URL, please send the following information to Toast support:

    • What happens in your system when you receive a webhook?

    • What is your workflow if your subscription is paused or stopped?

    • Will you be using message signing?

      What feedback do you have about the webhook and its documentation?

After Toast support enables your webhook in production, you are officially live on your new webhook subscription.