Subscribe to Events

Square Webhooks provides a client-level subscription model that allows an application to receive event notification types for all authorized merchants with 1 or more subscriptions.

An app that processes Webhooks notifications for multiple Square accounts may use a single webhook subscription for all of the accounts. This can reduce the amount of on-boarding work that a developer needs to do when bringing a new Square account on-line.

For more information about payments-related webhooks, read Payments and Refunds API Webhooks .

Subscribe for a webhook notification

Square Webhooks endpoints create a single event subscription for event types for a specified Square API version.

An application needs just one subscription per endpoint that it configures. That endpoint can handle all event types or any sub-set that the developer chooses. Use the Developer Dashboard Webhooks page to add as many webhooks as needed.

A webhook is configured with a notification URL, API version, and event type. This allows a developer to assign a notification endpoint to handle webhook events based on any combination of these properties. The API version is defaulted to the version pinned to the application registration but can be set to other versions.

Test the subscription

Once you have created a webhook endpoint and configured the subscription, you can quickly test your end point to see if it will handle the notification request correctly. To do this:

You can send this event to your webhook URL again by pressing the Send button on the confirmation page.

An example webhook test event notification

The object body of a test notification conforms to the data model of a production notification for the type notified. The object field values are fictional but formatted correctly. The following labor.shift.created test event notification shows a new Shift:

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "labor.shift.created",
  "event_id": "aeaaa5f6-c4fd-4e93-b688-71b50706266f",
  "created_at": "2019-10-29T17:26:16.808603647Z",
  "data": {
    "type": "labor",
    "id": "PY4YSMVKXFY9E",
    "object": {
      "shift": {
        "breaks": [
          {
            "break_type_id": "REGS1EQR1TPZ5",
            "end_at": "2019-01-25T11:16:00Z",
            "expected_duration": "PT5M",
            "id": "0EGK74E8BJF62",
            "is_paid": true,
            "name": "Tea Break",
            "start_at": "2019-01-25T11:11:00Z"
          }
        ],
        "created_at": "2019-11-06T19:14:55Z",
        "employee_id": "AnuhZhsN95oT8f-eCn9D",
        "end_at": "2019-01-25T18:11:00Z",
        "id": "PY4YSMVKXFY9E",
        "location_id": "NAQ1FHV6ZJ8YV",
        "start_at": "2019-01-25T08:11:00Z",
        "status": "CLOSED",
        "timezone": "Etc/UTC",
        "updated_at": "2019-11-06T19:14:55Z",
        "version": 1,
        "wage": {
          "hourly_rate": {
            "amount": 1100,
            "currency": "USD"
          },
          "title": "Barista"
        }
      }
    }
  }
}

Use this test to verify that your Validate Notifications logic is working.

Webhook events

The following events are available for Webhooks:

Bank Accounts

These webhooks send notification on the creation, verification, and disabling of a bank account.

Catalog

These webhooks send a notification when any changes are made to a catalog. An update to the state of any catalog object, image, or info in a Square account catalog.

Devices

These webhooks send a notification when a request to pair a device such as a Square Terminal with a custom POS succeeds.

Disputes

These webhooks send a notification when a dispute is created, updated, or dispute evidence is changed.

Inventory

These webhooks send a notification when a the count of an inventory item is changed due to an API call or Square POS action. The notifications can be used to synchronise off-line inventory with Square.

Invoices

The Invoices API supports webhook notifications for the following events:

All webhooks include the invoice ID and the invoice resource, for example:

{
  "merchant_id": "MERCHANT_ID",
  "location_id": "LOCATION_ID",
  "type": "invoice.canceled",
  "event_id": "UNIQUE_EVENT_ID",
  "created_at": "2019-10-25T23:01:51Z",
  "data": {
    "type": "invoice",
    "id": "INVOICE_ID",
    "object": <The invoice resource>
  }
}  

Labor

These webhooks send a notification when an employee starts a shift, takes a break, and ends their shift.

Loyalty

These webhooks send a notification on loyalty program events.

OAuth

These webhooks send a notification on revocation of an authorization.

Order

These webhooks send a notification when an order is created or updated, and order fulfillment is updated.

Payments

These webhooks send a notification when a payment is created or its status changes.

Refunds

These webhooks send a notification when a refund is created or its status changes.

Subscriptions

The Subscriptions API supports the following webhooks:

The webhook message has the following format:

{
  "merchant_id": "{{MERCHANT_TOKEN}}",
  "type": "subscription.updated",
  "event_id": "f4e988a9-ecba-4ae0-ba80-5e02dexample",
  "created_at": "2020-01-07T21:50:46.704Z",
  "data": {
    "type": "subscription",
    "id": "{SUBSCRIPTION_ID}",
    "object": {
        "subscription": {
            {{INSTANCE_OF_Subscription_TYPE}}
        }
    }
}

Terminal

These webhooks send a notification when a Square terminal checkout request is created or updated with a new status.