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

Add a Webhook Callback URL

Add a callback URL to your app on the Edit App page in the Developer Dashboard. Note that Clover only supports HTTPS-enabled callbacks.

Setup for Testing Webhooks

Webhooks require a publicly accessible endpoint (localhost will not work). You may wish to use one of the following services for testing:

  • RequestBin – Allows you to create a temporary endpoint for testing
  • Pagekite – Syncs your local server to a public endpoint (yourname.pagekite.me)
  • ngrok – Connects your local server to a public endpoint (http://subdomain.ngrok.com)

Subscribing to Events

You can subscribe to webhook event types under the Webhooks section of the Edit App page.

Each subscription requires the corresponding read permission. 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.

Verification Process

Once you click Verify, a POST request will be sent to your webhook URL with a JSON body that looks like this:

 {"verificationCode":"ce7643c1-83ea-4218-abe6-da876c9c7a0a"}

Note

The response to our server’s request from your URI must be a 200 SUCCESS code. Otherwise the attempt will fail with Bad response status: Internal Server Error.

Enter the verificationCode in the Verification Code field of the Edit App page (click Resend Code to get a new code). Once the verification code has been validated, your webhook subscription is verified and you will start receiving notifications.

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"

You may want to perform extra validation to ensure your webhook messages are coming from Clover.

Message Format

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

  • appId – The app ID the webhook was set up for
  • merchants – A map of [“merchantId” -> List of updates]
  • updates – A map containing the objectId, type, and timestamp

Example

{
    "appId":"DRKVJT2ZRRRSC",
    "merchants":
    {
        "XYZVJT2ZRRRSC":[
            {
                "objectId":"O:GHIVJT2ABCRSC",
                "type":"CREATE",
                "ts":1398202762787
            },
            {
                "objectId":"O:ABCVJTABCRRSC",
                "type":"UPDATE",
                "ts":1398203002815
            }
        ],
        "MNOVJT2ZRRRSC":[
            ...
        ]
    }
}

Update Message Format

  • objectId<Key For Event Type>:<Event Object ID>
  • typeCREATE, UPDATE, or DELETE
  • ts – The current time in milliseconds

Keys for Event Type

The objectId above contains a key at the beginning to specify an event type. Clover webhook event types are as follows:

  • A : Apps – When your app is installed, uninstalled, or the subscription is changed
  • C : Customers – When customers are created or updated
  • I : Inventory – When inventory items are created, updated, or deleted
  • O : Orders – When orders are created, updated, or deleted
  • P : Payments – When payments are created or updated
  • M : Merchants – When merchant properties are changed, or new merchants are added
  • CA : Cash Adjustments – When there is a cash log event (requires HTTPS)