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.

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

Configuring a 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.

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.
{"verificationCode":"ce7643c1-83ea-4218-abe6-da876c9c7a0a"}

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.

"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

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)
{
    "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

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
  • 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

Updated 5 months ago


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.