Square Webhooks

Subscribe to Events

Subscribe to Square Webhooks 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 Permalink Get a link to this section

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.

Important

The notification URL must be formatted correctly, use the HTTPS protocol, and be reachable. Otherwise, the error message "Your webhook for webhook was not created. URL is not valid" is displayed when you click Save.

CreateWebhook

Test the subscription Permalink Get a link to this section

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:

  1. Click on the webook event you want to test. A Webhook Details dialog opens.

  2. Click More on the bottom of the dialog to open a context menu.

  3. Click Send Test Event to send an event to the event listener that you set up at the endpoint.

  4. Choose then event type that you want to send.

SendTestEvent

  1. Click Send to send the chosen event type to your webhook URL. A confirmation page opens and shows you the notification body that was sent.

SentTestEvent

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 Permalink Get a link to this section

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 Permalink Get a link to this section

The following events are available for Webhooks:

Bank Accounts Permalink Get a link to this section

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

WebhookDescription
bank_account.disabledPublished when Square sets the status of a bank account to DISABLED.
bank_account.verifiedPublished when Square sets the status of a bank account to VERIFIED.
bank_account.createdPublished when you link an external bank account to a Square account in the seller dashboard. Square sets the initial status to VERIFICATION_IN_PROGRESS and publishes the event.

Catalog Permalink Get a link to this section

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.

WebhookDescription
catalog.version.updatedThe catalog was updated.
Webhook notification data is packaged as:
"catalog_version": { "updated_at": "2019-05-14T17:51:27Z"}.

Devices Permalink Get a link to this section

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

WebhookDescription
device.code.pairedA Square Terminal has been paired with a Terminal API client and the device_id of the paired Square Terminal is available.

Disputes Permalink Get a link to this section

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

WebhookDescription
dispute.createdA Dispute was created
dispute.state.changedThe State of a dispute changed.
This includes the dispute resolution (WON, LOST) reported by the bank. The event data includes details of what changed.
dispute.evidence.addedEvidence was added to a Dispute from the Disputes Dashboard in the Seller Dashboard, the Square Point of Sale app, or by calling CreateDisputeEvidence.
dispute.evidence.removedEvidence was removed from a Dispute from the Disputes Dashboard in the Seller Dashboard, the Square Point of Sale app, or by calling RemoveDisputeEvidence.

Inventory Permalink Get a link to this section

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.

WebhookDescription
inventory.count.updatedThe quantity was updated for a catalog item variation.
Webhook notification data is packaged as: InventoryCount[]

Invoices Permalink Get a link to this section

The Invoices API supports webhook notifications for the following events:

Event Description
invoice.created A new invoice is created.
invoice.updated An invoice has changed.
invoice.published An invoice is published or is scheduled for publication.
invoice.payment_made A payment is made for an invoice.
invoice.scheduled_charge_failed A scheduled charge has failed.
invoice.canceled An invoice is canceled.
invoice.refunded A refund is processed for an invoice.
invoice.deleted An invoice is deleted.

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 Permalink Get a link to this section

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

WebhookDescription
labor.shift.createdA worker started a shift.
Webhook notification data is packaged as a Shift
labor.shift.updatedA Shift was updated.
Typically a break was started, ended, or a worker ended the shift.
Webhook notification data is packaged as a Shift
labor.shift.deletedA Shift was deleted.
Notification data includes the deleted Shift ID and isDeleted flag.

Loyalty Permalink Get a link to this section

These webhooks send a notification on loyalty program events.

Webhook Description
loyalty.account.created Published when a loyalty account is created for a buyer. A loyalty account can be created using any of the following methods and they all publish this event:
  • Using the Loyalty API CreateLoyaltyAccount endpoint.
  • The buyer might enroll in the program at the Square point of sale.
  • Manually on the Seller Dashboard.
  • The seller might use the Customer Directory merge feature to merge two customer accounts into one account. In this process, sellers might merge the two corresponding Square loyalty accounts by creating a new account and deleting existing accounts.
loyalty.account.updated Published for any updates to a buyer's existing loyalty account. For example:
  • If the seller updates the phone number associated with a loyalty account using the Seller Dashboard. For more information, see Square Loyalty FAQ.
  • Any change in the loyalty point balance, such as points added for visits, points expiration, or a manual adjustment to the point balance that a seller might perform.
  • Customer ID of the loyalty account changes. Perhaps the loyalty account moves to another customer.
loyalty.account.deleted Published when a loyalty account is deleted. The published event does not contain the customer_id that was associated with the (deleted) account. The following actions to delete the account can publish this event:
  • The seller uses the Seller Dashboard to delete an account.
  • The seller might use the Customer Directory merge feature to merge two customer accounts into one account In this process, sellers might merge the two corresponding Square loyalty accounts by creating a new account and deleting existing accounts.
loyalty.program.updated Published when the loyalty program is updated from the Seller Dashboard.
loyalty.event.created Square loyalty maintains a ledger of events occurring in the lifetime of a loyalty account of a buyer. Square publishes this webhook for each loyalty event Square logs to the ledger. Loyalty events are immutable, they are never updated or deleted For example, when a buyer redeems a reward then returnds it, a CREATE_REWARD event and a DELETE_REWARD event are published separately. Similarly, when a purchase that accrued points is refunded, the deduction of points publishes the ADJUST_POINTS event.

OAuth Permalink Get a link to this section

These webhooks send a notification on revocation of an authorization.

WebhookDescription
oauth.authorization.revokedA webhook for notifying an application whenever a seller revokes all access tokens and refresh tokens granted to the application.

Order Permalink Get a link to this section

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

WebhookDescription
order.createdAn Order was created. This event is triggered only by the CreateOrder endpoint call.
order.fulfillment.updatedAn OrderFulfillment was created or updated. This event is triggered only by the UpdateOrder endpoint call.
order.updatedAn Order was updated. This event is triggered only by the UpdateOrder endpoint call.

Payments Permalink Get a link to this section

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

WebhookDescription
payment.createdA Payment was created.
payment.updatedA Payment was updated.
Typically the payment.status or card_details.status fields are updated as a payment is canceled, authorized, or completed.

Refunds Permalink Get a link to this section

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

WebhookDescription
refund.createdA Refund was created.
refund.updatedA Refund was updated.
Typically the refund.status changes when a refund is completed.

Subscriptions Permalink Get a link to this section

The Subscriptions API supports the following webhooks:

Webhook Description
subscription.updated Published whenever the Subscription object changes.
subscription.created Published when a Subscription object is created.

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 Permalink Get a link to this section

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

WebhookDescription
terminal.checkout.createdA TerminalCheckout request was created.
terminal.checkout.updatedThe status of a TerminalCheckout was changed

Next steps

Now that you are subscribed to events, add code to validate webhook notifications.