Use webhooks

Webhooks send you notifications when merchants who have installed your app perform certain events, such as creating an inventory or updating an order. For example, if you have Read Inventory permission and the merchant updates their inventory, you can set up webhooks to receive a POST request to an endpoint you specified. See Set up a test URL for webhooks.

Prerequisites

• Install your app on the test merchant. See Install your test app.
• Provide the Read permission that is required to receive webhook notifications for an event. For example, the Read Inventory permission is needed for events related to the inventory item webhooks. See Event type keys.
• Set up a publicly accessible HTTPs endpoint on your app as a webhook receiver. Localhost does not work for webhooks.

Set up a test URL for webhooks

You must have a simple web server running on your computer that can receive a webhook setup request and verification code. You can:

• Create a web server and test the webhook notifications. You can use a tool, such as Postman, for testing. See Use Postman to test your webhook.
• Use one of the following tools to make your localhost available for testing after your web server is running:
  • 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)

Step 1: Configure a callback link (URL)

You need to configure a callback link (URL) to receive notifications. Clover supports only HTTPS-enabled callbacks. The response to the server's request from your URL needs to be a 200 OK code. To configure a callback URL:

1. Log in to your sandbox Developer Dashboard.
2. From the left navigation menu, click Your Apps > App name > App Settings. The App name - App Settings page appears.
3. Click Webhooks. The Edit Webhooks page appears.
4. In the Webhook URL field, enter a callback link (URL). Example: You can use Postman to create a mock server link (URL) and then use it in the Webhook URL field:https://021f8db8-195b-45b2-b7ae-0c4173efcdfb.mock.pstmn.io/nwtr.

5. Click Send Verification Code.
   • The Verification Code field displays on the Edit Webhooks page.
   • A POST request with a verification code is sent to your callback URL.

{"verificationCode":"5220ecf5-7dea-4396-bOba-a1659c182887"}

6. From the POST request, copy the verificationCode value, paste it in the Verification Code field, and then click Verify.

7. Click Save. The Events Subscriptions section displays on the Edit Webhooks page.

Step 2: Subscribe to event types

You need to subscribe to event types to send webhook notifications based on event triggers in your app.

1. After you complete the steps to configure your callback URL, you can subscribe to categories of event types in the Edit Webhooks—Events Subscriptions section.

2. Select a checkbox to subscribe to an event type.
3. Click Save. The webhook callback URL and verification code displays in the Webhooks section on the App Settings page.

🚧

IMPORTANT

Each event type 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, see Set app permissions.

Step 3: Validate and test notifications success rate

After the webhook setup for an event is complete, you receive webhook requests at the callback URL each time the event occurs.

Verify the Clover auth code header

Use the Clover Auth Code key to verify that your webhook messages originate from Clover.

1. Log in to the Developer Dashboard.
2. From the left navigation menu, click Your Apps > App name > App Settings. The App name - App Settings page appears. The Webhooks section displays the Clover Auth Code key. This key displays in every message header after the webhook callback URL is validated.

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

Test webhook notifications

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

1. Log in to the Merchant Dashboard.
2. From the left menu, click Inventory > Item. The available items appear.
3. Select an item checkbox. The Item Basics page appears.
4. Edit the item name and click Save. Clover sends out a notification to the webhook endpoint.

Sample notification

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

Understand the message format and event objects

Webhook message format

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

Update object

Each update is indicated by a JSON or XML object for the webhook event containing the following information:

Event type keys

The objectId value begins with a key to indicate the event type. The Clover webhook event types are as follows:

Troubleshoot webhook notifications

If you are not receiving webhook notifications, use the following checklist:

Appendix: Use Postman to test your webhook

If you have a Postman account, you can use it to create a mock server for the callback link (URL), get a verification code, and test your webhook.

Step 1: Create a Webhook collection in Postman

1. Log in to Postman and access your Workspace.
2. Click Create New Collection > Blank Collection. The New Collection page appears.
3. Rename the new collection to indicate your webhook collection, for example, NewWebhookTest.
4. In the left navigation menu, under the new collection, click Add a request.

The HTTP/Webhook Collection/New Request displays a blank GET Request page.

5. Replace the New Request with the name of your request, for example, NWTR, to indicate a new webhook test request.
6. From the HTTP method drop-down list, select POST and enter the new request name, that is, NWTR.
   Note: POST webhook requests respond to the request body and also contain properties like authentication tokens.
7. Click Save.
8. In the left navigation menu, click the ellipsis icon next to the POST request and click Add example.

An example is added under the POST request.

9. In the POST request—Body section, enter a sample response, for example, {"testResponse： "pass"}.

10. Click Save.

Step 2: Create a mock server

Mock servers let you simulate API endpoints by returning example responses linked to each request.

1. After you create a POST request for your webhook collection, you need to run it as a server.
2. In the left navigation menu, click the ellipsis icon next to the webhook collection name and click Mock collection.

The Create a mock server page appears.

3. In the Mock Server Name field, enter the POST request name, for example, NWTR.
4. Click Create Mock Server. After the server is running, when a request is sent, the logs display on the Mock server calls page.
5. From the top right corner, click Copy URL to copy the mock server link (URL). You need this URL to set up webhooks in your Developer Dashboard. See Step 1: Configure a callback link (URL).
6. In your Postman Workspace, click Refresh Logs and copy the verification code that displays.

7. In the Developer Dashboard—Edit Webhooks page, in the Verification Code field, enter the copied verification code and click Verify.
8. Complete steps to test webhook notifications, and in your Postman Workspace, click Refresh Logs. Review the notification payload that displays.