The Sync API provides a mechanism for receiving update notifications when objects are created, updated, or deleted within TableCheck's systems.

Target audience

The Sync API should be used in combination with other APIs. The Sync API is recommended for use by:

• Web Booking vendors who wish to receive notifications when reservations are made.

• POS, CRM, IPTV, etc. vendors who wish to receive notifications when relevant objects change.

Endpoints

Interactive API console

https://api.tablecheck.com/api/sync/v1/docs

Refer to Using the API Console for help.

Rate Limits

These limits only apply to requests you make the TableCheck API. There is no enforced limit to the rate at which we will deliver webhook callbacks to your API.

How to Implement

A general flow of API implementation is as follows:

1. Before using Sync, first implement the flow of whichever API you intend to use (refer to Components.)

2. Use the PUT /webhooks endpoint to enable the sync feature and configure your callback URL.

3. Receive event callbacks at your specified URL, and call the appropriate API to fetch updated objects based on the ID contained within the events.

4. As an alternative, periodically poll the /sync_events endpoint to get the latest changed object IDs.

Configuring your Webhook Callback URL

🔗 API Console

Using the API, you programmatically configure the Webhook(s) by which SyncEvents will be delivered to your specified URL. You may specify multiple Webhooks, and may additionally limit certain Webhooks to specific Shops or Franchises. Refer to the API Console for details.

Handling Sync Webhook Callbacks

After configuring your webhook URL as per above, each time an object is updated you will receive a POST or PUT (depending on config) to that URL with a SyncEvent object that looks as follows:

Please note the following regarding Sync webhook callbacks:

• The SyncEvent object does not contain the actual data of the underlying object. To fetch the underlying data, please refer to the other APIs to which you have access. For example, if you are using the CRM API and you receive the above SyncEvent containing a customer object with ID ca1fd893e2Zae5355337ed5d6, you would query it as follows: GET /crm/v1/customers/ca1fd893e2Zae5355337ed5d6

• When using both the Sync webhooks, and Messaging webhooks, please note that when a given system event occurs, the order in which the Sync and Messaging webhooks are delivered is not guaranteed. Your Sync webhook handler should not depend on any data received via your Messaging webhook handler and vice-versa.

Please also note differences between the webhooks and SyncEvent API endpoint (below):

• Webhook objects will not be wrapped with { "sync_events": [ … ] }.

• Webhook objects will not include certain fields which are present on the API, for example updated_at, delivered_at, and response_code.

Authenticating Webhook Callbacks

By default, no authentication is used on webhook callbacks. The following methods can be configured:

Handling Webhook Delivery Failure

In order for the Sync API to mark a given SyncEvent as “delivered”, your callback endpoint must return an HTTP 2xx success status (e.g. “HTTP 200 OK”). Request delivery will timeout after 10 seconds, and failed requests will be retried twice for a total of three (3) delivery attempts.

You may set Account.notify_emails to specify email address(es) to notify when there is a webhook failure. A maximum of one (1) notification per hour will be delivered to each email, regardless of the number of webhook failures.

Failed messages are kept in TableCheck’s database and may be retreived via polling as explained in the following section.

Using the Sync API via Polling (without Webhooks)

🔗 API Console

As an alternative to using webhooks, you may poll the /sync_events endpoint to receive a list of SyncEvent objects. These objects are equivalent to the payload of the webhooks described above, and should be handled in the same manner. By default, this endpoint will only return SyncEvents which have not yet been delivered. Set the query parameter deliver=true so that all results returned will be flagged as "delivered" and will not be returned when you query the endpoint again.

Although we recommended to poll using the above URL pattern, you may also query poll for undelivered events created within a specific time range. In this case, to ensure no events are missed, we recommend to query for a longer time range (e.g. 1 hour) even if you are polling every 30 seconds.

Please note the following regarding SyncEvent API polling:

• There may be additional fields present in SyncEvent objects returned via the API that are not present when using webhooks. (The meaning and usage of fields present in both the API and webhooks are guaranteed to be the same.)

• The maximum time range that can be queried using the created_at_min and created_at_max parameters is 24 hours.

• A maximum of 1,000 results will be returned in each query. This endpoint does not support pagination.

Checking Delivery Status of SyncEvents

🔗 API Console

You may use the same /sync_eventsendpoint to check which SyncEvents were delivered (e.g. for troubleshooting purposes) using the following URL query:

Please note the following:

• In the response, delivery_method indicates whether the SyncEvent was first successfully delivered via "webhook" or "api" (polling).

• Specifying the delivered_at_min and delivered_at_max parameters (see example above) will only return delivered SyncEvents. The maximum time range that can be queried is 24 hours.

• All other queries will only return non-delivered SyncEvents, unless you specify include_delivered=true.

• A maximum of 1,000 results will be returned in each query. This endpoint does not support pagination.

Tips for Handling Sync Events

• It is recommended to handle created and updated both uniformly as an upsert, i.e.

  • If the ID does not exist in your database → create a new object

  • If the ID does exist in your database → update the existing object ID

• Similarly, it is recommended to ignore deleted events for objects whose ID does not exist in your database.

• If you receive a created or updated event but get a 404 when attempting to retrieve the actual object from the API, you may consider the object to be deleted. The API cannot guarantee the exact sequence of events.