Receive Vendors Webhook Events

When a vendor is created or updated in the backend, you might want to update your application to synchronize with the newly created or updated vendor. For example, when a vendor's status is updated, you want to be notified so that you don't attempt in your application to send a purchase order to the vendor if its status has become INACTIVE. To get your application notified of vendor-created or vendor-updated events, you can use Square API webhooks.

When a vendor is created or updated, a vendor.created or vendor.updated event is sent, respectively, through the Vendors API webhook to applications that have registered to receive the event notification. Your application can parse the received event data and act on the information following your application's business logic.

The following discussion presents a walkthrough to illustrate how to subscribe to the Vendors API webhook events for your application and how to parse the received event data in your application.

In particular, it covers the following tasks:

• Configuring your application to receive the vendor.created or vendor.updated event through the Vendors API webhook.
• Inspecting received vendor.created or vendor.updated event data.

To test receiving the webhook events, follow the instructions in Create Vendors for a Square Seller and Update Vendor Information to have the vendor.created and vendor.updated events fired, respectively.

To subscribe to the Vendors API event notifications, you must register your application with the Square API webhook through which Square sends notifications to the application. For more information, see Square Webhooks Overview.

To subscribe to vendor.created or vendor.updated event notifications, configure the webhook for your Square application as follows.

To configure a webhook

1. In the Developer Dashboard, open the application to which you want to subscribe.

2. In the left pane, choose Webhooks.

3. At the top of the page, choose Sandbox or Production. Choose Sandbox for testing.

4. Choose Add Endpoint, and then configure the endpoint:

   1. For Webhook Name, enter a name such as Vendors API Webhook.
   2. For URL, enter your notification URL. If you don't have a working URL yet, you can enter https://example.com as a placeholder. To use Webhook.site for testing, copy the Your unique URL on the website and paste it in the URL box.
   3. Optional. For API Version, choose a Square API version. By default, this is set to the same version as the application.
   4. For Events, choose vendor.created and vendor.updated. If you want to receive notifications about other events at the same webhook URL, choose them or configure another endpoint.
   5. Choose Save.
   Note

   In the production environment, ignore the Enable Webhooks setting on the Webhooks page. This setting applies to webhooks for deprecated Connect V1 APIs.

With the webhook configured, you can proceed to test the webhook workflow as follows.

When a new vendor is created, using either the Square API or Seller Dashboard, an instance of the vendor.created event is sent to your application registered for the webhook event.

The following example shows a vendor.created webhook event received when a vendor is created:

{
  "merchant_id": "ETCE****QDYP",
  "type": "vendor.created",
  "event_id": "4edd919d-ed19-492d-bcb0-1a1ef65dda1a",
  "created_at": "2022-03-16T01:04:37.308555597Z",
  "data": {
    "type": "vendor",
    "id": "5b041563-c3fa-4989-baaf-dec90e81de0b",
    "object": {
      "operation": "CREATED",
      "vendor": {
        "address": {
          "administrative_district_level_1": "NY",
          "country": "US",
          "locality": "New York",
          "postal_code": "10003"
        },
        "contacts": [
          {
            "email_address": "[email protected]",
            "id": "W43ANBJLR5UAV7WT",
            "name": "Joe Burrow",
            "ordinal": 0,
            "phone_number": "1-212-555-4250"
          }
        ],
        "created_at": "2022-03-16T01:04:12.581Z",
        "id": "BXIDSDOUIU34VY2V",
        "name": "Vendor 20",
        "status": "ACTIVE",
        "updated_at": "2022-03-16T01:04:12.581Z",
        "version": 1
      }
    }
  }
}

When an existing vendor is updated, an instance of the vendor.updated event is sent to your application.

The following example shows a vendor.updated event received when the vendor's name is updated from A Vendor to Macro Brewing and a note of Preferred beer supplier is added to the vendor:

{
  "merchant_id": "ETCE****QDYP",
  "type": "vendor.updated",
  "event_id": "1ae8cc43-bf73-48f6-a767-90bdfa197421",
  "created_at": "2022-03-16T01:15:35.780283073Z",
  "data": {
    "type": "vendor",
    "id": "1e8d9885-21dc-41b9-8a8f-6ccf64da5462",
    "object": {
      "operation": "UPDATED",
      "vendor": {
        "address": {
          "administrative_district_level_1": "NY",
          "country": "US",
          "locality": "New York",
          "postal_code": "10003"
        },
        "contacts": [
          {
            "email_address": "[email protected]",
            "id": "W43ANBJLR5UAV7WT",
            "name": "Joe Burrow",
            "ordinal": 0,
            "phone_number": "1-212-555-4250"
          }
        ],
        "created_at": "2022-03-16T01:04:12.581Z",
        "id": "BXIDSDOUIU34VY2V",
        "name": "Macro Brewing",
        "note": "Preferred beer supplier",
        "status": "ACTIVE",
        "updated_at": "2022-03-16T01:15:35.774Z",
        "version": 2
      }
    }
  }
}