Using webhooks

Webhooks allow your application to receive notifications when merchants who have installed your app perform certain actions. If a merchant has granted you the READ_INVENTORY permission and they change their inventory, for example, you'll receive a POST to an endpoint you've specified.



We highly recommend that you test the success rate of notifications received through the webhook service.

Setting up a test URL for webhooks

Webhooks require a publicly accessible endpoint (localhost alone will not work). You must have a simple web server running on your machine that can receive a webhook setup request and verification code. Once that server is running, you can use one of the following tools to expose your localhost for testing:

  • ngrok: Connects your local server to a public endpoint (
  • Pagekite: Syncs your local server to a public endpoint ( (requires Python)

Configuring a callback URL



Clover supports only HTTPS-enabled callbacks. The response to the server's request from your URL must be a 200 OK code.

To configure a callback URL:

  1. On the sandbox Developer Dashboard, click App Settings on the side-nav.
  2. On the App Settings page, click Webhooks.
  3. On the Edit Webhooks modal that appears, type your callback URL in the Webhook URL field.
  4. Click SEND VERIFICATION CODE. A POST request containing a verification code is sent to your callback URL.
  5. From the POST request, copy the verificationCode value, paste it into the Verification Code field, and then click VERIFY.

Clover auth code header

After validating your webhook URL, the App Settings page on the sandbox Developer Dashboard shows a Clover Auth Code key that Clover sends in every message's header.


This code can be used for validation to ensure your webhook messages are coming from Clover.

Subscribing to events

Once you configure your callback URL, you can subscribe to categories of event types in the Webhook Subscriptions section of the Edit Webhooks page.

Each subscription requires the corresponding read permission from the merchant. If you change permissions after a merchant installs your app, the permissions won't update for that merchant until the merchant uninstalls and reinstalls the app.

For more information about permissions, see app permissions.

Webhook message format

The messages that Clover sends to your webhook URL contain the following information:

  • appId: The ID of the application sending data updates
  • merchants: Contains one or more merchant arrays represented by the merchant ID
  • updates: One or more update objects each containing an objectId, type of operation, and timestamp (ts)

Update objects

Each update is represented by an object containing the following information:

  • objectId: <key of event type>:<event object ID>
  • ts: The current Unix time in milliseconds

Event type keys

The objectId value begins with a key to specify the event type. Clover webhook event types are as follows:

  • A: Apps: Your app is installed, uninstalled, or the subscription is changed



You can also use our out-of-the-box install and revenue metrics.

  • C: Customers: A customer is created, updated, or deleted
  • CA: Cash Adjustments: A cash log event occurs
  • E: Employees: An employee is created, updated, or deleted
  • I: Inventory: An inventory item is created, updated, or deleted
  • IC: Inventory Category: An inventory category is created, updated, or deleted
  • IG: Inventory Modifier Group: An inventory modifier group is created, updated, or deleted
  • IM: Inventory Modifier: An inventory modifier is created, updated, or deleted
  • O: Orders: An order is created, updated, or deleted
  • M: Merchants: A merchant property is changed or a new merchant is added
  • P: Payments: A payment is created or updated



If your app has already subscribed to inventory webhooks, you will need to unselect the inventory webhook, save the changes, and then re-select the inventory webhook and save again in order to start receiving the new inventory webhook messages.

Troubleshooting webhooks

If you are not receiving notifications, check the following:

  • Ensure that your app is installed on your test merchant.

  • Verify that your URL is correct.

  • Verify that your given URL is set up to accept POST requests.

  • Ensure that you are subscribed to the event type for which you want to receive a notification.

  • Verify that your app has the required permissions for that event type. For example, the inventory read permission is needed for inventory item webhooks.

  • If you changed your app permissions after you installed your app to your test merchant, you need to uninstall/reinstall your app on that test merchant for the new permissions to take effect.

Did this page help you?