Subscribe to Events

Square webhooks provide a client-level subscription model that allows an application to receive event notification types for all authorized sellers with one or more subscriptions.

An application that processes webhook notifications for multiple Square accounts can use a single webhook subscription for all the accounts. This can reduce the amount of onboarding work that a developer needs to do when bringing a new Square account online.

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

Subscribe for a webhook notification

Square webhook 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 subset that the developer chooses. Use the application's Webhooks setting page in the Developer Dashboard 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

When you have created a webhook endpoint and configured the subscription, you can quickly test your endpoint to see whether it handles the notification request correctly. To do this:

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

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. These changes include an update to the state of any catalog object, image, or information 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 or updated or when dispute evidence is changed.

Inventory

These webhooks send a notification when the count of an inventory item is changed due to an API call or Square POS action. The notifications can be used to synchronize an offline 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 a shift.

Locations

These webhooks send a notification when a location is created or updated.

Loyalty

These webhooks send a notification when loyalty program events occur.

OAuth

These webhooks send a notification when an authorization is revoked.

Order

These webhooks send a notification when an order is created or updated and when an 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.

Related topics

• Validate Notifications

• Notification Delivery SLA

• Webhooks API: How It Works