🔗 Webhooks

How to utilize webhooks to integrate Waitwhile with other external systems.

Waitwhile supports setting up webhooks for various events. This can be done for a specific location on the Integration Settings page or through the API. For each webhook you can choose to receive all events or specific events and for which locations.

The following event types are supported:

  • visit.created
  • visit.updated
  • visit.removed
  • location-status.updated
  • message.created
  • message.updated

Webhooks use the same schema definitions as the API for representing objects.

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to that you did not receive the webhook. Failed webhook calls will be retried up to three times. If your endpoint consistently fails for more than three days the webhook will be deactivated.

Waitwhile will sign the webhook events it sends to your endpoints. We do so by including a signature in each event’s X-Waitwhile-Signature header. This allows you to validate that the events were sent by Waitwhile and not by a third party.

Before you can verify signatures, you need to retrieve your endpoint’s secret from the settings. Each secret is unique to the endpoint to which it corresponds.

The signature is created by concatenating webhook URL and payload as a UTF-8 string, and then creating a hash-based message authentication code (HMAC) with SHA-256, encoded using Base64. See example code below:

function verifyWebhookSignature(signature, url, payload, secret) {
return signature == crypto.createHmac('sha256', secret).update(Buffer.from(url + payload, 'utf-8')).digest('base64');
}

Adding and Configuring Webhooks within the UI

Webhooks can be added and configured for a location from the Integrations Settings page.

When adding a webhook endpoint you can choose to "Send all event types" or select specific event types.

After a webhook endpoint has been added (using a valid Endpoint URL), you can view endpoint activity, your Signing secret, make changes to the configuration, or disable or delete the endpoint.

🚧

Webhook Limits

There is a max limit of 5 webhooks per location and 5 account wide webhooks (where locationIds is unset). Integrations with Waitwhile that are set up through Zapier also utilize webhooks and count against the 5 webhook limit.