Platform Docs

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.

NOTE

Clover does not guarantee when, or if, notifications will be received through the webhook service. If you require a more robust solution, you may either implement your own or use an external message delivery service.

Set Up Webhooks

Set Up a Testing 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 (http://subdomain.ngrok.com)
  • Pagekite - Syncs your local server to a public endpoint (yourname.pagekite.me) (requires Python)

Add a Webhook Callback URL

NOTE

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

Configure the Callback URL

  1. On your app's Settings page, click Webhooks.
  2. On the Webhooks page, type your callback URL in the Webhook URL field.
  3. Click Confirm. A POST request containing a verification code is sent to the URL.
  4. Copy the verificationCode value, paste it into the Verification Code field, and then click Verify.
{"verificationCode":"ce7643c1-83ea-4218-abe6-da876c9c7a0a"}

Clover Auth Code Header

After validating your webhook URL, the Edit App page shows a Clover Auth Code key that Clover will send in every message's header. The header is formatted in the following way:

"X-Clover-Auth":"0307e264-b33a-4913-88aa-37b10014a0b8"

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

Subscribing to Events

You can subscribe to categories of event types in the Webhook Subscriptions section of the 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.

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)
{
    "appId":"DRKVJT2ZRRRSC",
    "merchants":
    {
        "XYZVJT2ZRRRSC":[
            {
                "objectId":"O:GHIVJT2ABCRSC",
                "type":"CREATE",
                "ts":1537970958000
            },
            {
                "objectId":"O:ABCVJTABCRRSC",
                "type":"UPDATE",
                "ts":1536156558000
            }
        ],
        "MNOVJT2ZRRRSC":[
            ...
        ]
    }
}

Update Objects

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

  • objectId - <key of event type>:<event object ID>
  • type - CREATE, UPDATE, or DELETE
  • ts - The current Unix time in milliseconds

Keys for Event Type

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
  • 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 - A inventory item is created, updated, or deleted
  • O: Orders - An orders 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

Using webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.