Use webhooks

Webhooks allow your application to receive notifications when merchants who have installed your app perform certain actions. For example, if a merchant has granted you READ_INVENTORY permission and changes their inventory, you'll receive a POST to an endpoint that you specified.

📘

NOTE

Clover recommends that you test the success rate of notifications received through the webhook service.

Prerequisites

• Install your app on test merchant.
  See Installing your test app.
• Provide the permissions that the app requires for the respective event type. For example, the READ_INVENTORY permission is needed for inventory item webhooks.
  See app permissions.

Set up a test URL for webhooks

Webhooks require a publicly accessible endpoint as only a localhost will not work. You must have a simple web server running on your computer that can receive a webhook setup request and verification code. Once the web server is running, you can use one of the following tools to make your localhost available 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)

Configure 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. Log in to the sandbox Developer Dashboard, click App Settings on the side-nav.
2. From the left navigation menu, click App Settings.
3. On the App Settings page, click Webhooks. The Edit Webhooks page appears.
4. In the Webhook URL field, enter your callback URL.
5. Click Send Verification Code. A POST request containing a verification code is sent to your callback URL.
6. 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 header.

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

Use this auth code for validation to ensure your webhook messages originate from Clover.

Subscribe 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 on the sandbox Developer Dashboard .

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: Identifier (ID) of the application sending data updates.
• merchants: Contains one or more merchant arrays indicated by the merchant identifier (mID).
• 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 indicated by an object containing the following information:

• objectId: <key of event type>:<event object ID>
• type: CREATE, UPDATE, or DELETE
• ts: Current Unix time. Format: milliseconds

Event type keys

The objectId value begins with a key to indicate the event type. The 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: 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

👍

TIP

To gain insights into the performance of your published apps, you can use out-of-the-box install and revenue metrics.

📘

NOTE

If your app is already subscribed to inventory webhooks, you need to:

• Clear the inventory webhook and save the changes.
• Reselect the inventory webhook and save it again to start receiving the new inventory webhook messages.

Troubleshoot webhooks

If you are not receiving notifications:

• Verify that your webhook URL is correct.
• Verify that the webhook 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 required permissions for that event type. For example, the READ_INVENTORY permission is needed for inventory item webhooks.
• If you change the app permissions after installing the app to your test merchant, you need to uninstall and then reinstall the app on the test merchant for the new permissions to take effect.