Learn how to call the Vendors API to set up webhooks to receive supported Vendors API event notifications.
Vendors API

Receive Vendors Webhook Events Beta release
This is pre-release documentation for an API in public beta and is subject to change.

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 do not 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.

Overview Permalink Get a link to this section

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 and Update Vendor Information to have the vendor.created and vendor.updated events fired, respectively.

Subscribe to the Vendors API event notifications Permalink Get a link to this section

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 do not 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.

Inspect the vendor.created event Permalink Get a link to this section

When a new vendor is created, using either the Square API or Square 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:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
{
  "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": "joe@joesfreshseafood.com",
            "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
      }
    }
  }
}

Inspect the vendor.updated event Permalink Get a link to this section

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:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
{
  "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": "joe@joesfreshseafood.com",
            "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
      }
    }
  }
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.