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 the  READ_INVENTORY permission and they change their inventory, you’ll receive a POST to an endpoint you’ve specified.

Set Up Webhooks

Add Webhook Callback URL

Add a callback URL to your app on your Edit App page in the Developer Dashboard. We only support HTTPS-enabled callbacks.

Subscribing to Events

When editing your app, the Webhooks section lists the webhook event types that you can subscribe to.

Each subscription requires the corresponding Read permission. If permissions are changed after the app is installed by the merchant, the app must be uninstalled and reinstalled to update the permissions.

Verification Process

As soon as you click Verify, a POST request will be sent to your webhook URL with a JSON body 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 like this:

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

You may want to do 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 that the webhook was set up for
  • merchants – Map of [“merchantId” -> List of updates]
  • updates – Map containing objectId, type, and timestamp

An example and other information relevant to the messages can be found below.

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)