How to 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.
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 choose Save.
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:
Choose the webhook event you want to test. A Webhook Details dialog opens.
Choose More at the bottom of the dialog to open a context menu.
Choose Send Test Event to send an event to the event listener that you set up at the endpoint.
Choose the event type that you want to send.
Choose Send to send the chosen event type to your webhook URL. A confirmation page opens and shows you the notification body that was sent.
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.
Webhook | Description |
---|---|
bank_account.disabled | Published when Square sets the status of a bank account to DISABLED. |
bank_account.verified | Published when Square sets the status of a bank account to VERIFIED. |
bank_account.created | Published 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. |
Bookings
These webhooks send notification on the creation and update of a booking.
Webhook | Description |
---|---|
booking.created | Published when a new booking is created by calling the CreateBooking endpoint of the Bookings API. |
booking.updated | Published when an accepted or pending booking is updated. |
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.
Webhook | Description |
---|---|
catalog.version.updated | The catalog was updated. Webhook notification data is packaged as "catalog_version": { "updated_at": "2019-05-14T17:51:27Z"} . |
Customers
These webhooks send a notification when a customer profile is created, updated, or deleted. For more information, see Use Customer Webhooks.
Webhook | Description |
---|---|
customer.created (beta) | A customer profile is created, including when customer profiles are merged into a new customer profile. |
customer.deleted (beta) | A customer profile is deleted, including when customer profiles are merged into a new customer profile. |
customer.updated (beta) | An attribute on a customer profile is changed, except for the following: • cards • segment_ids • groups (deprecated) |
Devices
These webhooks send a notification when a request to pair a device, such as a Square Terminal with a custom POS, succeeds.
Webhook | Description |
---|---|
device.code.paired | A Square Terminal has been paired with a Terminal API client and the device_id of the paired Square Terminal is available. |
Disputes
These webhooks send a notification when a dispute is created or updated or when dispute evidence is changed.
Webhook | Description |
---|---|
dispute.created | A dispute was created. |
dispute.state.changed | The state of a dispute changed. This includes the dispute resolution (WON or LOST) reported by the bank. The event data includes details about what changed. |
dispute.evidence.added | Evidence was added to a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling the Disputes API (CreateDisputeEvidenceFile or CreateDisputeEvidenceText). |
dispute.evidence.removed | Evidence was removed from a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling RemoveDisputeEvidence. |
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.
Webhook | Description |
---|---|
inventory.count.updated | The quantity was updated for a catalog item variation. Webhook notification data is packaged as InventoryCount[]. |
Invoices
The Invoices API supports webhook notifications for the following events:
Event | Description |
invoice.created
|
A new invoice was created. |
invoice.updated
|
An invoice has changed. |
invoice.published
|
An invoice was published or is scheduled for publication. |
invoice.payment_made
|
A payment was made for an invoice. |
invoice.scheduled_charge_failed
|
A scheduled charge has failed. |
invoice.canceled
|
An invoice was canceled. |
invoice.refunded
|
A refund was processed for an invoice. |
invoice.deleted
|
An invoice was 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
These webhooks send a notification when an employee starts a shift, takes a break, and ends a shift.
Webhook | Description |
---|---|
labor.shift.created | A worker started a shift. Webhook notification data is packaged as a Shift. |
labor.shift.updated | A shift was updated. Typically a break was started or ended or a worker ended the shift. Webhook notification data is packaged as a Shift. |
labor.shift.deleted | A shift was deleted. Notification data includes the deleted shift ID and the isDeleted flag. |
Locations
These webhooks send a notification when a location is created or updated.
Webhook | Description |
---|---|
location.created | A Location was created. |
location.updated | A Location was updated. |
Loyalty
These webhooks send a notification when loyalty program events occur.
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:
|
loyalty.account.updated | Published for any updates to a buyer's existing loyalty account. For example:
|
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:
|
loyalty.program.updated | Published when the loyalty program is updated in 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, which means they are never updated or deleted. For example, when a buyer redeems a reward and then returns 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
These webhooks send a notification when an authorization is revoked.
Webhook | Description |
---|---|
oauth.authorization.revoked | A webhook for notifying an application whenever a seller revokes all access tokens and refresh tokens granted to the application. |
Order
These webhooks send a notification when an order is created or updated and when an order fulfillment is updated.
Webhook | Description |
---|---|
order.created | An Order was created. This event is triggered only by the CreateOrder endpoint call. |
order.fulfillment.updated | An OrderFulfillment was created or updated. This event is triggered only by the UpdateOrder endpoint call. |
order.updated | An Order was updated. This event is triggered only by the UpdateOrder endpoint call. |
Note
In the current implementation, a webhook is not generated for orders and payments activity from all POS.
Payments
These webhooks send a notification when a payment is created or its status changes.
Webhook | Description |
---|---|
payment.created | A Payment was created. |
payment.updated | A Payment was updated. Typically the payment.status or card_details.status field is updated when a payment is canceled, authorized, or completed. |
Refunds
These webhooks send a notification when a refund is created or its status changes.
Webhook | Description |
---|---|
refund.created | A Refund was created. |
refund.updated | A Refund was updated. Typically the refund.status field changes when a refund is completed. |
Subscriptions
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
These webhooks send a notification when a Square terminal checkout request is created or updated with a new status.
Webhook | Description |
---|---|
terminal.checkout.created | A TerminalCheckout request was created. |
terminal.checkout.updated | The status of a TerminalCheckout was changed. |