Webhook Events Reference

Learn about the V2 webhooks for Square API endpoints.

Link to section

Overview

Webhooks let you subscribe to Square API events and receive notice when an event occurs. For more information about how to set up a webhook subscription, see Square Webhooks.

Link to section

Bank Accounts API

EventPermissionDescription
bank_account.disabledBANK_ACCOUNTS_READPublished when Square sets the status of a bank account to DISABLED.
bank_account.verifiedBANK_ACCOUNTS_READPublished when Square sets the status of a bank account to VERIFIED.
bank_account.createdBANK_ACCOUNTS_READPublished when you link a seller's or buyer's bank account to a Square account. Square sets the initial status to VERIFICATION_IN_PROGRESS and publishes the event.

For information about using the Bank Accounts API, see Bank Accounts API.

Link to section

Bookings API

EventPermissionDescription
booking.createdAPPOINTMENTS_READA booking is created by calling CreateBooking.
booking.updatedAPPOINTMENTS_READAn API-created booking is updated in the Square Dashboard, on the seller's online booking site, or by calling UpdateBooking.

For more information about booking events, see Handle Booking Event Notifications with Webhooks. For information about using the Bookings API, see Manage Bookings for Square Sellers.

Link to section

Booking Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

EventDescription
booking.custom_attribute_definition.owned.createdA custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
boooking.custom_attribute_definition.owned.updatedA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
booking.custom_attribute_definition.owned.deletedA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
booking.custom_attribute.owned.updatedA custom attribute owned by your application was created or updated for a booking.
booking.custom_attribute.owned.deletedA custom attribute owned by your application was deleted from a booking.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you don't need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

EventDescription
booking.custom_attribute_definition.visible.createdA custom attribute definition that's visible to your application was created.
booking.custom_attribute_definition.visible.updatedA custom attribute definition that's visible to your application was updated.
booking.custom_attribute_definition.visible.deletedA custom attribute definition that's visible to your application was deleted.
booking.custom_attribute.visible.updatedA custom attribute that's visible to your application was created or updated for a booking.
booking.custom_attribute.visible.deletedA custom attribute that's visible to your application was deleted from a booking.

For more information about booking-related custom attribute events, see Webhooks. For information about using the Booking Custom Attributes API, see Custom Attributes for Bookings.

Link to section

Cards API

EventPermissionDescription
card.automatically_updatedPAYMENTS_READPublished when card expiration information or PAN is automatically updated.
card.createdPAYMENTS_READPublished when a card is created or imported.
card.disabledPAYMENTS_READPublished when a card is disabled.
card.forgottenPAYMENTS_READPublished when a card is GDPR forgotten or vaulted.
card.updatedPAYMENTS_READPublished when a card is updated by the developer using the UpdateCard endpoint.

For information about using the Cards API, see Cards API.

Link to section

Catalog API

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

For more information about catalog events, see Webhooks. For information about using the Catalog API, see What It Does.

Link to section

Checkout API

EventPermissionDescription
online_checkout.location_settings.updatedMERCHANT_PROFILE_WRITE, MERCHANT_PROFILE_READPublished when online checkout location settings are updated.
online_checkout.merchant_settings.updatedMERCHANT_PROFILE_WRITE, MERCHANT_PROFILE_READPublished when online checkout merchant settings are updated.

For information about using the Checkout API, see Checkout API.

Link to section

Customers API

EventPermission Description
customer.createdCUSTOMERS_READA customer profile is created, including when customer profiles are merged into a new customer profile.
customer.deletedCUSTOMERS_READA customer profile is deleted, including when customer profiles are merged into a new customer profile.
customer.updatedCUSTOMERS_READAn attribute on a customer profile is changed, except for the following:
  • cards (deprecated)
  • segment_ids

For more information about customer events, see Use Customer Webhooks. For information about using the Customers API, see Manage Customers and Integrate with Other Services.

Link to section

Customer Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

EventPermissionDescription
customer.custom_attribute_definition.owned.createdCUSTOMERS_READA custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.

This event replaces the deprecated customer.custom_attribute_definition.created event.
customer.custom_attribute_definition.owned.updatedCUSTOMERS_READA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.

This event replaces the deprecated customer.custom_attribute_definition.updated event.
customer.custom_attribute_definition.owned.deletedCUSTOMERS_READA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.

This event replaces the deprecated customer.custom_attribute_definition.deleted event.
customer.custom_attribute.owned.updatedCUSTOMERS_READA custom attribute owned by your application was created or updated for a customer profile.

This event replaces the deprecated customer.custom_attribute.updated event.
customer.custom_attribute.owned.deletedCUSTOMERS_READA custom attribute owned by your application was deleted from a customer profile.

This event replaces the deprecated customer.custom_attribute.deleted event.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

EventPermissionDescription
customer.custom_attribute_definition.visible.createdCUSTOMERS_READA custom attribute definition that's visible to your application was created.

This event replaces the deprecated customer.custom_attribute_definition.public.created event.
customer.custom_attribute_definition.visible.updatedCUSTOMERS_READA custom attribute definition that's visible to your application was updated.

This event replaces the deprecated customer.custom_attribute_definition.public.updated event.
customer.custom_attribute_definition.visible.deletedCUSTOMERS_READA custom attribute definition that's visible to your application was deleted.

This event replaces the deprecated customer.custom_attribute_definition.public.deleted event.
customer.custom_attribute.visible.updatedCUSTOMERS_READA custom attribute that's visible to your application was created or updated for a customer profile.

This event replaces the deprecated customer.custom_attribute.public.updated event.
customer.custom_attribute.visible.deletedCUSTOMERS_READA custom attribute that's visible to your application was deleted from a customer profile.

This event replaces the deprecated customer.custom_attribute.public.deleted event.

For more information about customer-related custom attribute events, see Webhooks. For information about using the Customer Custom Attributes API, see Custom Attributes for Customer Profiles.

Link to section

Devices API

EventPermissionDescription
device.code.pairedDEVICE_CREDENTIAL_MANAGEMENTA Square Terminal has been paired with a Terminal API client and the device_id of the paired Square Terminal is available.
device.createdDEVICES_READA new Square Terminal was created. This means the Square Terminal has been associated with the given seller's account.

For information about using the Devices API, see Connect a Square Terminal and Terminal Device Monitoring.

Link to section

Disputes API

EventPermissionDescription
dispute.createdPAYMENTS_READA dispute was created.
DEPRECATED: dispute.state.changedPAYMENTS_READThe 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.state.updatedPAYMENTS_READThe 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.
DEPRECATED: dispute.evidence.addedPAYMENTS_READEvidence was added to a dispute from the Disputes Dashboard in the Square Dashboard, in the Square Point of Sale application, or by calling the Disputes API (CreateDisputeEvidenceFile or CreateDisputeEvidenceText).
dispute.evidence.createdPAYMENTS_READEvidence was added to a dispute from the Disputes Dashboard in the Square Dashboard, in the Square Point of Sale application, or by calling the Disputes API (CreateDisputeEvidenceFile or CreateDisputeEvidenceText).
dispute.evidence.deletedPAYMENTS_READEvidence was removed from a dispute from the Disputes Dashboard in the Square Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence.
DEPRECATED: dispute.evidence.removedPAYMENTS_READEvidence was removed from a dispute from the Disputes Dashboard in the Square Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence.

For more information about dispute events, see Disputes webhook notifications. For information about using the Disputes API, see Disputes API.

Link to section

Gift Cards API

EventPermissionDescription
gift_card.createdGIFTCARDS_READA digital gift card was created or a physical gift card was registered.
gift_card.updatedGIFTCARDS_READA gift card was updated. The balance_money, state, and customer_ids fields of a gift card can be updated through a gift card activity or when a customer is linked or unlinked.
gift_card.customer_linkedGIFTCARDS_READA customer was linked to a gift card.
gift_card.customer_unlinkedGIFTCARDS_READA customer was unlinked from a gift card.
gift_card.activity.createdGIFTCARDS_READA gift card activity was created.
gift_card.activity.updatedGIFTCARDS_READA REDEEM or IMPORT gift card activity was updated.

For REDEEM activities, this event is invoked when the status changes from PENDING to COMPLETED or CANCELED. This status change applies only when the gift card was redeemed using Square Point of Sale or the Square Dashboard.

For IMPORT activities, this event is invoked when the balance of an imported third-party gift card is updated by Square.

For more information about gift card events, see Gift Card Webhooks. For information about using the Gift Cards API and Gift Card Activities API, see Gift Cards API.

Link to section

Inventory API

EventPermission Description
inventory.count.updatedINVENTORY_READThe quantity was updated for a catalog item variation. Webhook notification data is packaged as InventoryCount[].

For information about using the Inventory API, see What It Does.

Link to section

Invoices API

EventPermission Description
invoice.createdINVOICES_READA draft invoice was created.
invoice.publishedINVOICES_READAn invoice was published. This also applies to invoices that are published but scheduled to be processed at a later time.
invoice.updatedINVOICES_READAn invoice was changed. This event is also invoked following invoice.published and invoice.canceled events.
invoice.payment_madeINVOICES_READA payment was made for an invoice.
invoice.scheduled_charge_failedINVOICES_READA scheduled automatic payment has failed.
invoice.canceledINVOICES_READAn invoice was canceled.
invoice.refundedINVOICES_READA refund was processed for an invoice.
invoice.deletedINVOICES_READA draft invoice was deleted. A deleted invoice is removed entirely from the seller account (including any attachments) and cannot be retrieved.

For information about using the Invoices API, see Invoices API.

Link to section

Labor API

EventPermissionDescription
labor.shift.createdTIMECARDS_READA worker started a shift.
Webhook notification data is packaged as a Shift.
labor.shift.updatedTIMECARDS_READA 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.deletedTIMECARDS_READA shift was deleted.
Notification data includes the deleted shift ID and the isDeleted flag.

For information about using the Labor API, see Labor API.

Link to section

Locations API

EventPermissionDescription
location.createdMERCHANT_PROFILE_READA Location was created.
location.updatedMERCHANT_PROFILE_READA Location was updated.

For information about using the Locations API, see Locations API.

Link to section

Location Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

EventPermissionDescription
location.custom_attribute_definition.owned.createdMERCHANT_PROFILE_READA custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
location.custom_attribute_definition.owned.updatedMERCHANT_PROFILE_READA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
location.custom_attribute_definition.owned.deletedMERCHANT_PROFILE_READA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
location.custom_attribute.owned.updatedMERCHANT_PROFILE_READA custom attribute owned by your application was created or updated for a location.
location.custom_attribute.owned.deletedMERCHANT_PROFILE_READA custom attribute owned by your application was deleted from a location.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application. Therefore, you do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

EventPermissionDescription
location.custom_attribute_definition.visible.createdMERCHANT_PROFILE_READA custom attribute definition that's visible to your application was created.
location.custom_attribute_definition.visible.updatedMERCHANT_PROFILE_READA custom attribute definition that's visible to your application was updated.
location.custom_attribute_definition.visible.deletedMERCHANT_PROFILE_READA custom attribute definition that's visible to your application was deleted.
location.custom_attribute.visible.updatedMERCHANT_PROFILE_READA custom attribute that's visible to your application was created or updated for a location.
location.custom_attribute.visible.deletedMERCHANT_PROFILE_READA custom attribute that's visible to your application was deleted from a location.

For more information about location-related custom attribute events, see Webhooks. For information about using the Location Custom Attributes API, see Custom Attributes for Locations.

Link to section

Loyalty API

EventPermission Description
loyalty.account.createdLOYALTY_READA loyalty account was created for a buyer. A loyalty account can be created using any of the following methods, which all publish this event:
  • An application calls the CreateLoyaltyAccount endpoint.
  • A buyer enrolls in the program from a Square Point of Sale application.
  • The seller enrolls a buyer using the Customer Directory.
  • The seller merges two customer accounts into one account using the Customer Directory. In this process, sellers might merge the two corresponding loyalty accounts by creating a new account and deleting the existing accounts.
loyalty.account.updatedLOYALTY_READA loyalty account was updated. For example:
  • The seller updates the phone number registered for the loyalty account using the Square 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.
  • The customer ID of the loyalty account was changed. For example, the loyalty account moved to another customer.
loyalty.account.deletedLOYALTY_READPublished 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 deletes an account using the Square Dashboard.
  • The seller merges two customer profiles using the Customer Directory. In this process, sellers might merge the two corresponding loyalty accounts by creating a new account and deleting the existing accounts.
loyalty.program.createdLOYALTY_READA loyalty program was created. Loyalty programs can only be created from the Square Dashboard.
loyalty.program.updatedLOYALTY_READA loyalty program was updated. Loyalty programs can only be updated from the Square Dashboard.
loyalty.promotion.createdLOYALTY_READA loyalty promotion was created.
loyalty.promotion.updatedLOYALTY_READA loyalty promotion was canceled.
loyalty.event.createdLOYALTY_READA balance-changing event occurred. Square Loyalty maintains a ledger of events that occur over the lifetime of a loyalty account. Square publishes notifications for each loyalty event logged to the ledger. These loyalty events are immutable, which means they are never updated or deleted. For example, when a buyer redeems a reward and then returns the order, Square publishes separate notifications for the corresponding CREATE_REWARD and DELETE_REWARD events. Similarly, Square publishes a notification for the OTHER event when points are deducted after a purchase that accrued points is refunded.

For information about using the Loyalty API, see Loyalty API.

Link to section

Merchant Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

EventPermissionDescription
merchant.custom_attribute_definition.owned.createdMERCHANT_PROFILE_READA custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
merchant.custom_attribute_definition.owned.updatedMERCHANT_PROFILE_READA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
merchant.custom_attribute_definition.owned.deletedMERCHANT_PROFILE_READA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
merchant.custom_attribute.owned.updatedMERCHANT_PROFILE_READA custom attribute owned by your application was created or updated for a merchant.
merchant.custom_attribute.owned.deletedMERCHANT_PROFILE_READA custom attribute owned by your application was deleted from a merchant.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application. Therefore, you don't need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

EventPermissionDescription
merchant.custom_attribute_definition.visible.createdMERCHANT_PROFILE_READA custom attribute definition that's visible to your application was created.
merchant.custom_attribute_definition.visible.updatedMERCHANT_PROFILE_READA custom attribute definition that's visible to your application was updated.
merchant.custom_attribute_definition.visible.deletedMERCHANT_PROFILE_READA custom attribute definition that's visible to your application was deleted.
merchant.custom_attribute.visible.updatedMERCHANT_PROFILE_READA custom attribute that's visible to your application was created or updated for a merchant.
merchant.custom_attribute.visible.deletedMERCHANT_PROFILE_READA custom attribute that's visible to your application was deleted from a merchant.

For information about using the Merchant Custom Attributes API, see Custom Attributes for Merchants.

Link to section

OAuth API

EventPermissionDescription
oauth.authorization.revokedN/ANotifies an application whenever a seller revokes all access tokens and refresh tokens granted to the application.

For information about using the OAuth API, see OAuth API.

Link to section

Orders API

Events on an Order object can be triggered by your Orders API call or by a seller's action on an order within a Square product such as the Square Point of Sale.

EventPermissionDescription
order.createdORDERS_READAn Order was created. This event is triggered when an order is created by a Square product or your application.
order.fulfillment.updatedORDERS_READAn OrderFulfillment was created or updated. This event is triggered when a Square product updates an order fulfillment or when a fulfillment is updated by an UpdateOrder endpoint call.
order.updatedORDERS_READAn Order was updated. This event is triggered only by the UpdateOrder endpoint call or when a seller updates an order using a Square product.

For information about using the Orders API, see Orders API.

Link to section

Order Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

EventPermissionDescription
order.custom_attribute_definition.owned.createdORDERS_READA custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
order.custom_attribute_definition.owned.updatedORDERS_READA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
order.custom_attribute_definition.owned.deletedORDERS_READA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
order.custom_attribute.owned.updatedORDERS_READA custom attribute owned by your application was created or updated for an order.
order.custom_attribute.owned.deletedORDERS_READA custom attribute owned by your application was deleted from an order.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

EventPermissionDescription
order.custom_attribute_definition.visible.createdORDERS_READA custom attribute definition that's visible to your application was created.
order.custom_attribute_definition.visible.updatedORDERS_READA custom attribute definition that's visible to your application was updated.
order.custom_attribute_definition.visible.deletedORDERS_READA custom attribute definition that's visible to your application was deleted.
order.custom_attribute.visible.updatedORDERS_READA custom attribute that's visible to your application was created or updated for an order.
order.custom_attribute.visible.deletedORDERS_READA custom attribute that's visible to your application was deleted from an order.

For information about using the Order Custom Attributes API, see Custom Attributes for Orders.

Link to section

Payments API

EventPermissionDescription
payment.createdPAYMENTS_READA Payment was created.
payment.updatedPAYMENTS_READA Payment field was updated. For example, the payment.status or card_details.status field is updated when a payment is authorized, canceled, or completed.

For information about using the Payments API, see Payments API.

Link to section

Payouts API

EventPermissionDescription
payout.failedPAYOUTS_READA Payout has failed.
payout.paidPAYOUTS_READA Payout was completed.
payout.sentPAYOUTS_READA Payout was sent.

For information about using the Payouts API, see Payouts API.

Link to section

Refunds API

EventPermissionDescription
refund.createdPAYMENTS_READA Refund was created.
refund.updatedPAYMENTS_READA Refund was updated. Typically, the refund.status field changes when a refund is completed.

For information about using the Refunds API, see Refunds API.

Link to section

Subscriptions API

EventPermissionDescription
subscription.createdSUBSCRIPTIONS_READA Subscription object was created.
subscription.updatedSUBSCRIPTIONS_READA Subscription object was updated.

For information about using the Subscriptions API, see Manage Subscriptions Using the Subscriptions API.

Link to section

Team API

EventPermission Description
team_member.createdEMPLOYEES_READA new team member was created.
team_member.updatedEMPLOYEES_READA team member was updated.
team_member.wage_setting.updatedEMPLOYEES_READA team member wage setting was updated.

For information about using the Team API, see Team API.

Link to section

Terminal API

EventPermission Description
terminal.checkout.createdPAYMENTS_READA TerminalCheckout request was created.
terminal.checkout.updatedPAYMENTS_READA TerminalCheckout status was changed.
terminal.refund.createdPAYMENTS_READA TerminalRefund request was created.
terminal.refund.updatedPAYMENTS_READA TerminalRefund status was changed.
terminal.action.createdPAYMENTS_READA TerminalAction request was created.
terminal.action.updatedPAYMENTS_READA TerminalAction status was updated.

For information about using the Terminal API, see Terminal API.

Link to section

Vendors API

EventPermission Description
vendor.createdVENDOR_READPublished when a vendor is created by calling CreateVendor or BulkCreateVendors, as well as using the Square Dashboard.
vendor.updatedVENDOR_READPublished when a vendor is updated by calling UpdateVendor or BulkUpdateVendors, as well as using the Square Dashboard.

For more information about vendor events, see Receive Vendors Webhook Events. For information about using the Vendors API, see Manage Suppliers of a Seller.