Subscribe to Events
Subscribe to Square Connect v2 Webhooks (beta).
v2 Webhooks (beta) 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 Square v2 Webhooks (beta) notifications for multiple Square accounts may use a single v2 Webhooks (beta) subscription for all of the accounts. This can reduce the amount of onboarding work that a developer needs to do when bringing a new Square account online.
On this page
Webhook events
The following events are available for v2 Webhooks (beta):
| 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. |
catalog.version.updated | The catalog was updated. Webhook notification data is packaged as:"catalog_version": { "updated_at": "2019-05-14T17:51:27Z"}. |
dispute.created | A Dispute was created |
dispute.state.changed | The 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.added | Evidence 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.removed | Evidence was removed from a Dispute from the Disputes Dashboard in the Seller Dashboard, the Square Point of Sale app, or by calling RemoveDisputeEvidence. |
inventory.count.updated | The quantity was updated for a catalog item variation. Webhook notification data is packaged as: InventoryCount[] |
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, 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 isDeleted flag. |
payment.created | A Payment was created. |
payment.updated | A Payment was updated. Typically the payment.status or card_details.status fields are updated as a payment is canceled, authorized, or completed. |
refund.created | A Refund was created. |
refund.updated | A Refund was updated. Typically the refund.status changes when a refund is completed. |
For more information about payments-related webhooks, read Payments and Refunds API Webhooks.
Subscribe to a webhook
Square v2 Webhooks (beta) 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.
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:
Click on the webook event you want to test. A Webhook Details dialog opens.
Click More on the bottom of the dialog to open a context menu.
Click Send Test Event to send an event to the event listener that you set up at the endpoint.
Choose then event type that you want to send.
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.
You can send this event to your webhook URL again by pressing the Send button on the confirmation page.
An example v2 Webhooks (beta) 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.