Square · AsyncAPI Specification

Square Webhooks

Version 1.0.0

AsyncAPI 2.6 description of the Square webhook event surface. Square delivers HTTPS POST notifications to a subscriber-provided `notification_url` whenever an event occurs on a seller's account. Each notification body is a JSON object with `merchant_id`, `location_id` (when applicable), `type`, `event_id`, `created_at`, and a `data` envelope containing the affected object. Each request is signed using HMAC-SHA-256. The signing payload is the concatenation of the notification URL and the raw request body. The base64-encoded digest is delivered via the `x-square-hmacsha256-signature` HTTP header. Subscribers should compare signatures using a constant-time comparison function. Event types in this document are taken verbatim from the Square "Webhook Events Reference" (developer.squareup.com).

View Spec View on GitHub RestaurantBookingsCatalogCheckoutCustomersDisputesEcommerceFinancial TechnologyGift CardsInventoryInvoicingLaborLocationsLoyaltyMerchantsOrdersPaymentsPoint of SaleRefundsRetailSubscriptionsTeamTerminalWebhooksAsyncAPIWebhooksEvents

Channels

/
publish receiveSquareEvent
Receive a Square webhook event notification.
Single inbound channel that receives every Square webhook event type subscribed to by the application. The concrete event is discriminated by the `type` field on the message payload.

Messages

✉
BankAccountDisabled
bank_account.disabled
A bank account was disabled.
✉
BankAccountVerified
bank_account.verified
A bank account was verified.
✉
BankAccountCreated
bank_account.created
A bank account was linked to the seller.
✉
BookingCreated
booking.created
A booking was created.
✉
BookingUpdated
booking.updated
A booking was updated.
✉
BookingCustomAttributeDefinitionOwnedCreated
booking.custom_attribute_definition.owned.created
An owned booking custom attribute definition was created.
✉
BookingCustomAttributeDefinitionOwnedUpdated
booking.custom_attribute_definition.owned.updated
An owned booking custom attribute definition was updated.
✉
BookingCustomAttributeDefinitionOwnedDeleted
booking.custom_attribute_definition.owned.deleted
An owned booking custom attribute definition was deleted.
✉
BookingCustomAttributeOwnedUpdated
booking.custom_attribute.owned.updated
An owned booking custom attribute value was updated.
✉
BookingCustomAttributeOwnedDeleted
booking.custom_attribute.owned.deleted
An owned booking custom attribute value was deleted.
✉
BookingCustomAttributeDefinitionVisibleCreated
booking.custom_attribute_definition.visible.created
A visible booking custom attribute definition was created.
✉
BookingCustomAttributeDefinitionVisibleUpdated
booking.custom_attribute_definition.visible.updated
A visible booking custom attribute definition was updated.
✉
BookingCustomAttributeDefinitionVisibleDeleted
booking.custom_attribute_definition.visible.deleted
A visible booking custom attribute definition was deleted.
✉
BookingCustomAttributeVisibleUpdated
booking.custom_attribute.visible.updated
A visible booking custom attribute value was updated.
✉
BookingCustomAttributeVisibleDeleted
booking.custom_attribute.visible.deleted
A visible booking custom attribute value was deleted.
✉
CardAutomaticallyUpdated
card.automatically_updated
A card on file was automatically updated by the network.
✉
CardCreated
card.created
A card on file was created.
✉
CardDisabled
card.disabled
A card on file was disabled.
✉
CardForgotten
card.forgotten
A card on file was forgotten (data removed).
✉
CardUpdated
card.updated
A card on file was updated.
✉
CatalogVersionUpdated
catalog.version.updated
The seller's catalog version changed.
✉
OnlineCheckoutLocationSettingsUpdated
online_checkout.location_settings.updated
Online checkout location settings were updated.
✉
OnlineCheckoutMerchantSettingsUpdated
online_checkout.merchant_settings.updated
Online checkout merchant settings were updated.
✉
CustomerCreated
customer.created
A customer was created.
✉
CustomerDeleted
customer.deleted
A customer was deleted.
✉
CustomerUpdated
customer.updated
A customer was updated.
✉
CustomerCustomAttributeDefinitionOwnedCreated
customer.custom_attribute_definition.owned.created
An owned customer custom attribute definition was created.
✉
CustomerCustomAttributeDefinitionOwnedUpdated
customer.custom_attribute_definition.owned.updated
An owned customer custom attribute definition was updated.
✉
CustomerCustomAttributeDefinitionOwnedDeleted
customer.custom_attribute_definition.owned.deleted
An owned customer custom attribute definition was deleted.
✉
CustomerCustomAttributeOwnedUpdated
customer.custom_attribute.owned.updated
An owned customer custom attribute value was updated.
✉
CustomerCustomAttributeOwnedDeleted
customer.custom_attribute.owned.deleted
An owned customer custom attribute value was deleted.
✉
CustomerCustomAttributeDefinitionVisibleCreated
customer.custom_attribute_definition.visible.created
A visible customer custom attribute definition was created.
✉
CustomerCustomAttributeDefinitionVisibleUpdated
customer.custom_attribute_definition.visible.updated
A visible customer custom attribute definition was updated.
✉
CustomerCustomAttributeDefinitionVisibleDeleted
customer.custom_attribute_definition.visible.deleted
A visible customer custom attribute definition was deleted.
✉
CustomerCustomAttributeVisibleUpdated
customer.custom_attribute.visible.updated
A visible customer custom attribute value was updated.
✉
CustomerCustomAttributeVisibleDeleted
customer.custom_attribute.visible.deleted
A visible customer custom attribute value was deleted.
✉
DeviceCodePaired
device.code.paired
A device code was paired to a device.
✉
DeviceCreated
device.created
A new device was created.
✉
DisputeCreated
dispute.created
A dispute was created.
✉
DisputeStateChanged
dispute.state.changed
A dispute changed state.
✉
DisputeStateUpdated
dispute.state.updated
A dispute state was updated.
✉
DisputeEvidenceAdded
dispute.evidence.added
Evidence was added to a dispute.
✉
DisputeEvidenceCreated
dispute.evidence.created
Evidence was created for a dispute.
✉
DisputeEvidenceDeleted
dispute.evidence.deleted
Evidence was deleted from a dispute.
✉
DisputeEvidenceRemoved
dispute.evidence.removed
Evidence was removed from a dispute.
✉
GiftCardCreated
gift_card.created
A gift card was created.
✉
GiftCardUpdated
gift_card.updated
A gift card was updated.
✉
GiftCardCustomerLinked
gift_card.customer_linked
A customer was linked to a gift card.
✉
GiftCardCustomerUnlinked
gift_card.customer_unlinked
A customer was unlinked from a gift card.
✉
GiftCardActivityCreated
gift_card.activity.created
A gift card activity was created.
✉
GiftCardActivityUpdated
gift_card.activity.updated
A gift card activity was updated.
✉
InventoryCountUpdated
inventory.count.updated
One or more inventory counts changed.
✉
InvoiceCreated
invoice.created
An invoice was created.
✉
InvoicePublished
invoice.published
An invoice was published.
✉
InvoiceUpdated
invoice.updated
An invoice was updated.
✉
InvoicePaymentMade
invoice.payment_made
A payment was made on an invoice.
✉
InvoiceScheduledChargeFailed
invoice.scheduled_charge_failed
A scheduled invoice charge failed.
✉
InvoiceCanceled
invoice.canceled
An invoice was canceled.
✉
InvoiceRefunded
invoice.refunded
An invoice was refunded.
✉
InvoiceDeleted
invoice.deleted
An invoice was deleted.
✉
LaborScheduledShiftCreated
labor.scheduled_shift.created
A scheduled shift was created.
✉
LaborScheduledShiftUpdated
labor.scheduled_shift.updated
A scheduled shift was updated.
✉
LaborScheduledShiftPublished
labor.scheduled_shift.published
A scheduled shift was published.
✉
LaborScheduledShiftDeleted
labor.scheduled_shift.deleted
A scheduled shift was deleted.
✉
LaborTimecardCreated
labor.timecard.created
A timecard was created.
✉
LaborTimecardUpdated
labor.timecard.updated
A timecard was updated.
✉
LaborTimecardDeleted
labor.timecard.deleted
A timecard was deleted.
✉
LaborShiftCreated
labor.shift.created
A labor shift was created.
✉
LaborShiftUpdated
labor.shift.updated
A labor shift was updated.
✉
LaborShiftDeleted
labor.shift.deleted
A labor shift was deleted.
✉
LocationCreated
location.created
A location was created.
✉
LocationUpdated
location.updated
A location was updated.
✉
LocationCustomAttributeDefinitionOwnedCreated
location.custom_attribute_definition.owned.created
An owned location custom attribute definition was created.
✉
LocationCustomAttributeDefinitionOwnedUpdated
location.custom_attribute_definition.owned.updated
An owned location custom attribute definition was updated.
✉
LocationCustomAttributeDefinitionOwnedDeleted
location.custom_attribute_definition.owned.deleted
An owned location custom attribute definition was deleted.
✉
LocationCustomAttributeOwnedUpdated
location.custom_attribute.owned.updated
An owned location custom attribute value was updated.
✉
LocationCustomAttributeOwnedDeleted
location.custom_attribute.owned.deleted
An owned location custom attribute value was deleted.
✉
LocationCustomAttributeDefinitionVisibleCreated
location.custom_attribute_definition.visible.created
A visible location custom attribute definition was created.
✉
LocationCustomAttributeDefinitionVisibleUpdated
location.custom_attribute_definition.visible.updated
A visible location custom attribute definition was updated.
✉
LocationCustomAttributeDefinitionVisibleDeleted
location.custom_attribute_definition.visible.deleted
A visible location custom attribute definition was deleted.
✉
LocationCustomAttributeVisibleUpdated
location.custom_attribute.visible.updated
A visible location custom attribute value was updated.
✉
LocationCustomAttributeVisibleDeleted
location.custom_attribute.visible.deleted
A visible location custom attribute value was deleted.
✉
LoyaltyAccountCreated
loyalty.account.created
A loyalty account was created.
✉
LoyaltyAccountUpdated
loyalty.account.updated
A loyalty account was updated.
✉
LoyaltyAccountDeleted
loyalty.account.deleted
A loyalty account was deleted.
✉
LoyaltyProgramCreated
loyalty.program.created
A loyalty program was created.
✉
LoyaltyProgramUpdated
loyalty.program.updated
A loyalty program was updated.
✉
LoyaltyPromotionCreated
loyalty.promotion.created
A loyalty promotion was created.
✉
LoyaltyPromotionUpdated
loyalty.promotion.updated
A loyalty promotion was updated.
✉
LoyaltyEventCreated
loyalty.event.created
A loyalty event was created.
✉
MerchantCustomAttributeDefinitionOwnedCreated
merchant.custom_attribute_definition.owned.created
An owned merchant custom attribute definition was created.
✉
MerchantCustomAttributeDefinitionOwnedUpdated
merchant.custom_attribute_definition.owned.updated
An owned merchant custom attribute definition was updated.
✉
MerchantCustomAttributeDefinitionOwnedDeleted
merchant.custom_attribute_definition.owned.deleted
An owned merchant custom attribute definition was deleted.
✉
MerchantCustomAttributeOwnedUpdated
merchant.custom_attribute.owned.updated
An owned merchant custom attribute value was updated.
✉
MerchantCustomAttributeOwnedDeleted
merchant.custom_attribute.owned.deleted
An owned merchant custom attribute value was deleted.
✉
MerchantCustomAttributeDefinitionVisibleCreated
merchant.custom_attribute_definition.visible.created
A visible merchant custom attribute definition was created.
✉
MerchantCustomAttributeDefinitionVisibleUpdated
merchant.custom_attribute_definition.visible.updated
A visible merchant custom attribute definition was updated.
✉
MerchantCustomAttributeDefinitionVisibleDeleted
merchant.custom_attribute_definition.visible.deleted
A visible merchant custom attribute definition was deleted.
✉
MerchantCustomAttributeVisibleUpdated
merchant.custom_attribute.visible.updated
A visible merchant custom attribute value was updated.
✉
MerchantCustomAttributeVisibleDeleted
merchant.custom_attribute.visible.deleted
A visible merchant custom attribute value was deleted.
✉
OAuthAuthorizationRevoked
oauth.authorization.revoked
An OAuth authorization was revoked.
✉
OrderCreated
order.created
An order was created.
✉
OrderFulfillmentUpdated
order.fulfillment.updated
An order fulfillment was updated.
✉
OrderUpdated
order.updated
An order was updated.
✉
OrderCustomAttributeDefinitionOwnedCreated
order.custom_attribute_definition.owned.created
An owned order custom attribute definition was created.
✉
OrderCustomAttributeDefinitionOwnedUpdated
order.custom_attribute_definition.owned.updated
An owned order custom attribute definition was updated.
✉
OrderCustomAttributeDefinitionOwnedDeleted
order.custom_attribute_definition.owned.deleted
An owned order custom attribute definition was deleted.
✉
OrderCustomAttributeOwnedUpdated
order.custom_attribute.owned.updated
An owned order custom attribute value was updated.
✉
OrderCustomAttributeOwnedDeleted
order.custom_attribute.owned.deleted
An owned order custom attribute value was deleted.
✉
OrderCustomAttributeDefinitionVisibleCreated
order.custom_attribute_definition.visible.created
A visible order custom attribute definition was created.
✉
OrderCustomAttributeDefinitionVisibleUpdated
order.custom_attribute_definition.visible.updated
A visible order custom attribute definition was updated.
✉
OrderCustomAttributeDefinitionVisibleDeleted
order.custom_attribute_definition.visible.deleted
A visible order custom attribute definition was deleted.
✉
OrderCustomAttributeVisibleUpdated
order.custom_attribute.visible.updated
A visible order custom attribute value was updated.
✉
OrderCustomAttributeVisibleDeleted
order.custom_attribute.visible.deleted
A visible order custom attribute value was deleted.
✉
PaymentCreated
payment.created
A payment was created.
✉
PaymentUpdated
payment.updated
A payment was updated.
✉
PayoutFailed
payout.failed
A payout failed.
✉
PayoutPaid
payout.paid
A payout was paid.
✉
PayoutSent
payout.sent
A payout was sent.
✉
RefundCreated
refund.created
A refund was created.
✉
RefundUpdated
refund.updated
A refund was updated.
✉
SubscriptionCreated
subscription.created
A subscription was created.
✉
SubscriptionUpdated
subscription.updated
A subscription was updated.
✉
TeamMemberCreated
team_member.created
A team member was created.
✉
TeamMemberUpdated
team_member.updated
A team member was updated.
✉
TeamMemberWageSettingUpdated
team_member.wage_setting.updated
A team member wage setting was updated.
✉
JobCreated
job.created
A job was created.
✉
JobUpdated
job.updated
A job was updated.
✉
TerminalCheckoutCreated
terminal.checkout.created
A Terminal checkout was created.
✉
TerminalCheckoutUpdated
terminal.checkout.updated
A Terminal checkout was updated.
✉
TerminalRefundCreated
terminal.refund.created
A Terminal refund was created.
✉
TerminalRefundUpdated
terminal.refund.updated
A Terminal refund was updated.
✉
TerminalActionCreated
terminal.action.created
A Terminal action was created.
✉
TerminalActionUpdated
terminal.action.updated
A Terminal action was updated.
✉
TransferOrderCreated
transfer_order.created
A transfer order was created.
✉
TransferOrderUpdated
transfer_order.updated
A transfer order was updated.
✉
TransferOrderDeleted
transfer_order.deleted
A transfer order was deleted.
✉
VendorCreated
vendor.created
A vendor was created.
✉
VendorUpdated
vendor.updated
A vendor was updated.

Servers

https
subscriber {notification_url}
Subscriber-hosted HTTPS endpoint that receives Square webhook POST requests. The URL is registered with Square via the Webhook Subscriptions API or the Developer Dashboard.

AsyncAPI Specification

Raw ↑ 
asyncapi: 2.6.0
info:
  title: Square Webhooks
  version: '1.0.0'
  description: |
    AsyncAPI 2.6 description of the Square webhook event surface.

    Square delivers HTTPS POST notifications to a subscriber-provided
    `notification_url` whenever an event occurs on a seller's account.
    Each notification body is a JSON object with `merchant_id`,
    `location_id` (when applicable), `type`, `event_id`, `created_at`,
    and a `data` envelope containing the affected object.

    Each request is signed using HMAC-SHA-256. The signing payload is
    the concatenation of the notification URL and the raw request body.
    The base64-encoded digest is delivered via the
    `x-square-hmacsha256-signature` HTTP header. Subscribers should
    compare signatures using a constant-time comparison function.

    Event types in this document are taken verbatim from the Square
    "Webhook Events Reference" (developer.squareup.com).
  termsOfService: https://squareup.com/us/en/legal/general/ua
  contact:
    name: Square Developer Platform
    url: https://developer.squareup.com/docs/webhooks/overview
    email: [email protected]
  license:
    name: Square Developer Terms of Service
    url: https://squareup.com/us/en/legal/general/ua
  x-source-documentation:
    - https://developer.squareup.com/docs/webhooks/overview
    - https://developer.squareup.com/docs/webhooks/v2webhook-events-tech-ref
    - https://developer.squareup.com/docs/webhooks/step3validate
    - https://developer.squareup.com/docs/webhooks/webhook-subscriptions-api

defaultContentType: application/json

servers:
  subscriber:
    url: '{notification_url}'
    protocol: https
    description: |
      Subscriber-hosted HTTPS endpoint that receives Square webhook
      POST requests. The URL is registered with Square via the Webhook
      Subscriptions API or the Developer Dashboard.
    variables:
      notification_url:
        description: Fully qualified HTTPS URL configured on the subscription.
        default: https://example.com/square/webhooks
    security:
      - hmacSha256Signature: []

channels:
  /:
    description: |
      Single inbound channel that receives every Square webhook event
      type subscribed to by the application. The concrete event is
      discriminated by the `type` field on the message payload.
    publish:
      operationId: receiveSquareEvent
      summary: Receive a Square webhook event notification.
      description: |
        Square POSTs a JSON-encoded event envelope to the configured
        notification URL. The request includes the
        `x-square-hmacsha256-signature` header, which subscribers MUST
        verify before acting on the payload.
      bindings:
        http:
          type: request
          method: POST
          bindingVersion: 0.3.0
      message:
        oneOf:
          - $ref: '#/components/messages/BankAccountDisabled'
          - $ref: '#/components/messages/BankAccountVerified'
          - $ref: '#/components/messages/BankAccountCreated'
          - $ref: '#/components/messages/BookingCreated'
          - $ref: '#/components/messages/BookingUpdated'
          - $ref: '#/components/messages/BookingCustomAttributeDefinitionOwnedCreated'
          - $ref: '#/components/messages/BookingCustomAttributeDefinitionOwnedUpdated'
          - $ref: '#/components/messages/BookingCustomAttributeDefinitionOwnedDeleted'
          - $ref: '#/components/messages/BookingCustomAttributeOwnedUpdated'
          - $ref: '#/components/messages/BookingCustomAttributeOwnedDeleted'
          - $ref: '#/components/messages/BookingCustomAttributeDefinitionVisibleCreated'
          - $ref: '#/components/messages/BookingCustomAttributeDefinitionVisibleUpdated'
          - $ref: '#/components/messages/BookingCustomAttributeDefinitionVisibleDeleted'
          - $ref: '#/components/messages/BookingCustomAttributeVisibleUpdated'
          - $ref: '#/components/messages/BookingCustomAttributeVisibleDeleted'
          - $ref: '#/components/messages/CardAutomaticallyUpdated'
          - $ref: '#/components/messages/CardCreated'
          - $ref: '#/components/messages/CardDisabled'
          - $ref: '#/components/messages/CardForgotten'
          - $ref: '#/components/messages/CardUpdated'
          - $ref: '#/components/messages/CatalogVersionUpdated'
          - $ref: '#/components/messages/OnlineCheckoutLocationSettingsUpdated'
          - $ref: '#/components/messages/OnlineCheckoutMerchantSettingsUpdated'
          - $ref: '#/components/messages/CustomerCreated'
          - $ref: '#/components/messages/CustomerDeleted'
          - $ref: '#/components/messages/CustomerUpdated'
          - $ref: '#/components/messages/CustomerCustomAttributeDefinitionOwnedCreated'
          - $ref: '#/components/messages/CustomerCustomAttributeDefinitionOwnedUpdated'
          - $ref: '#/components/messages/CustomerCustomAttributeDefinitionOwnedDeleted'
          - $ref: '#/components/messages/CustomerCustomAttributeOwnedUpdated'
          - $ref: '#/components/messages/CustomerCustomAttributeOwnedDeleted'
          - $ref: '#/components/messages/CustomerCustomAttributeDefinitionVisibleCreated'
          - $ref: '#/components/messages/CustomerCustomAttributeDefinitionVisibleUpdated'
          - $ref: '#/components/messages/CustomerCustomAttributeDefinitionVisibleDeleted'
          - $ref: '#/components/messages/CustomerCustomAttributeVisibleUpdated'
          - $ref: '#/components/messages/CustomerCustomAttributeVisibleDeleted'
          - $ref: '#/components/messages/DeviceCodePaired'
          - $ref: '#/components/messages/DeviceCreated'
          - $ref: '#/components/messages/DisputeCreated'
          - $ref: '#/components/messages/DisputeStateChanged'
          - $ref: '#/components/messages/DisputeStateUpdated'
          - $ref: '#/components/messages/DisputeEvidenceAdded'
          - $ref: '#/components/messages/DisputeEvidenceCreated'
          - $ref: '#/components/messages/DisputeEvidenceDeleted'
          - $ref: '#/components/messages/DisputeEvidenceRemoved'
          - $ref: '#/components/messages/GiftCardCreated'
          - $ref: '#/components/messages/GiftCardUpdated'
          - $ref: '#/components/messages/GiftCardCustomerLinked'
          - $ref: '#/components/messages/GiftCardCustomerUnlinked'
          - $ref: '#/components/messages/GiftCardActivityCreated'
          - $ref: '#/components/messages/GiftCardActivityUpdated'
          - $ref: '#/components/messages/InventoryCountUpdated'
          - $ref: '#/components/messages/InvoiceCreated'
          - $ref: '#/components/messages/InvoicePublished'
          - $ref: '#/components/messages/InvoiceUpdated'
          - $ref: '#/components/messages/InvoicePaymentMade'
          - $ref: '#/components/messages/InvoiceScheduledChargeFailed'
          - $ref: '#/components/messages/InvoiceCanceled'
          - $ref: '#/components/messages/InvoiceRefunded'
          - $ref: '#/components/messages/InvoiceDeleted'
          - $ref: '#/components/messages/LaborScheduledShiftCreated'
          - $ref: '#/components/messages/LaborScheduledShiftUpdated'
          - $ref: '#/components/messages/LaborScheduledShiftPublished'
          - $ref: '#/components/messages/LaborScheduledShiftDeleted'
          - $ref: '#/components/messages/LaborTimecardCreated'
          - $ref: '#/components/messages/LaborTimecardUpdated'
          - $ref: '#/components/messages/LaborTimecardDeleted'
          - $ref: '#/components/messages/LaborShiftCreated'
          - $ref: '#/components/messages/LaborShiftUpdated'
          - $ref: '#/components/messages/LaborShiftDeleted'
          - $ref: '#/components/messages/LocationCreated'
          - $ref: '#/components/messages/LocationUpdated'
          - $ref: '#/components/messages/LocationCustomAttributeDefinitionOwnedCreated'
          - $ref: '#/components/messages/LocationCustomAttributeDefinitionOwnedUpdated'
          - $ref: '#/components/messages/LocationCustomAttributeDefinitionOwnedDeleted'
          - $ref: '#/components/messages/LocationCustomAttributeOwnedUpdated'
          - $ref: '#/components/messages/LocationCustomAttributeOwnedDeleted'
          - $ref: '#/components/messages/LocationCustomAttributeDefinitionVisibleCreated'
          - $ref: '#/components/messages/LocationCustomAttributeDefinitionVisibleUpdated'
          - $ref: '#/components/messages/LocationCustomAttributeDefinitionVisibleDeleted'
          - $ref: '#/components/messages/LocationCustomAttributeVisibleUpdated'
          - $ref: '#/components/messages/LocationCustomAttributeVisibleDeleted'
          - $ref: '#/components/messages/LoyaltyAccountCreated'
          - $ref: '#/components/messages/LoyaltyAccountUpdated'
          - $ref: '#/components/messages/LoyaltyAccountDeleted'
          - $ref: '#/components/messages/LoyaltyProgramCreated'
          - $ref: '#/components/messages/LoyaltyProgramUpdated'
          - $ref: '#/components/messages/LoyaltyPromotionCreated'
          - $ref: '#/components/messages/LoyaltyPromotionUpdated'
          - $ref: '#/components/messages/LoyaltyEventCreated'
          - $ref: '#/components/messages/MerchantCustomAttributeDefinitionOwnedCreated'
          - $ref: '#/components/messages/MerchantCustomAttributeDefinitionOwnedUpdated'
          - $ref: '#/components/messages/MerchantCustomAttributeDefinitionOwnedDeleted'
          - $ref: '#/components/messages/MerchantCustomAttributeOwnedUpdated'
          - $ref: '#/components/messages/MerchantCustomAttributeOwnedDeleted'
          - $ref: '#/components/messages/MerchantCustomAttributeDefinitionVisibleCreated'
          - $ref: '#/components/messages/MerchantCustomAttributeDefinitionVisibleUpdated'
          - $ref: '#/components/messages/MerchantCustomAttributeDefinitionVisibleDeleted'
          - $ref: '#/components/messages/MerchantCustomAttributeVisibleUpdated'
          - $ref: '#/components/messages/MerchantCustomAttributeVisibleDeleted'
          - $ref: '#/components/messages/OAuthAuthorizationRevoked'
          - $ref: '#/components/messages/OrderCreated'
          - $ref: '#/components/messages/OrderFulfillmentUpdated'
          - $ref: '#/components/messages/OrderUpdated'
          - $ref: '#/components/messages/OrderCustomAttributeDefinitionOwnedCreated'
          - $ref: '#/components/messages/OrderCustomAttributeDefinitionOwnedUpdated'
          - $ref: '#/components/messages/OrderCustomAttributeDefinitionOwnedDeleted'
          - $ref: '#/components/messages/OrderCustomAttributeOwnedUpdated'
          - $ref: '#/components/messages/OrderCustomAttributeOwnedDeleted'
          - $ref: '#/components/messages/OrderCustomAttributeDefinitionVisibleCreated'
          - $ref: '#/components/messages/OrderCustomAttributeDefinitionVisibleUpdated'
          - $ref: '#/components/messages/OrderCustomAttributeDefinitionVisibleDeleted'
          - $ref: '#/components/messages/OrderCustomAttributeVisibleUpdated'
          - $ref: '#/components/messages/OrderCustomAttributeVisibleDeleted'
          - $ref: '#/components/messages/PaymentCreated'
          - $ref: '#/components/messages/PaymentUpdated'
          - $ref: '#/components/messages/PayoutFailed'
          - $ref: '#/components/messages/PayoutPaid'
          - $ref: '#/components/messages/PayoutSent'
          - $ref: '#/components/messages/RefundCreated'
          - $ref: '#/components/messages/RefundUpdated'
          - $ref: '#/components/messages/SubscriptionCreated'
          - $ref: '#/components/messages/SubscriptionUpdated'
          - $ref: '#/components/messages/TeamMemberCreated'
          - $ref: '#/components/messages/TeamMemberUpdated'
          - $ref: '#/components/messages/TeamMemberWageSettingUpdated'
          - $ref: '#/components/messages/JobCreated'
          - $ref: '#/components/messages/JobUpdated'
          - $ref: '#/components/messages/TerminalCheckoutCreated'
          - $ref: '#/components/messages/TerminalCheckoutUpdated'
          - $ref: '#/components/messages/TerminalRefundCreated'
          - $ref: '#/components/messages/TerminalRefundUpdated'
          - $ref: '#/components/messages/TerminalActionCreated'
          - $ref: '#/components/messages/TerminalActionUpdated'
          - $ref: '#/components/messages/TransferOrderCreated'
          - $ref: '#/components/messages/TransferOrderUpdated'
          - $ref: '#/components/messages/TransferOrderDeleted'
          - $ref: '#/components/messages/VendorCreated'
          - $ref: '#/components/messages/VendorUpdated'

components:
  securitySchemes:
    hmacSha256Signature:
      type: httpApiKey
      in: header
      name: x-square-hmacsha256-signature
      description: |
        Each webhook request includes the `x-square-hmacsha256-signature`
        header. To verify authenticity, the subscriber computes
        HMAC-SHA-256 over the concatenation of the notification URL and
        the raw request body, using the signature key associated with
        the webhook subscription as the HMAC key. The resulting digest
        is base64-encoded and compared to the header value using a
        constant-time comparison.

  messageTraits:
    SquareWebhookHeaders:
      headers:
        type: object
        properties:
          x-square-hmacsha256-signature:
            type: string
            description: Base64-encoded HMAC-SHA-256 signature of (notification_url + raw_body).
          square-retry-number:
            type: string
            description: Present when the notification is a retry; ordinal of the retry attempt.
          square-retry-reason:
            type: string
            description: Present when the notification is a retry; reason for the retry.
          square-initial-delivery-timestamp:
            type: string
            description: Timestamp of the initial delivery attempt (present on retries).
        required:
          - x-square-hmacsha256-signature

  schemas:
    EventEnvelope:
      type: object
      description: Common envelope shape for all Square webhook event notifications.
      required:
        - merchant_id
        - type
        - event_id
        - created_at
        - data
      properties:
        merchant_id:
          type: string
          description: Identifier of the Square merchant the event belongs to.
        location_id:
          type: string
          description: Identifier of the location associated with the event, when applicable.
        type:
          type: string
          description: Event type name (e.g., `payment.created`).
        event_id:
          type: string
          format: uuid
          description: Unique identifier for the event, used for idempotency.
        created_at:
          type: string
          format: date-time
          description: RFC 3339 timestamp at which the event was generated.
        data:
          type: object
          description: Event-type-specific payload envelope.
          properties:
            type:
              type: string
              description: The Square object type carried in `object` (e.g., `payment`, `order`).
            id:
              type: string
              description: Identifier of the affected object.
            object:
              type: object
              description: |
                The affected object. Shape varies by event type. Refer to the
                corresponding Square REST API reference for the object schema.
              additionalProperties: true

  messages:
    BankAccountDisabled:
      name: bank_account.disabled
      title: bank_account.disabled
      summary: A bank account was disabled.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: bank_account.disabled

    BankAccountVerified:
      name: bank_account.verified
      title: bank_account.verified
      summary: A bank account was verified.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: bank_account.verified

    BankAccountCreated:
      name: bank_account.created
      title: bank_account.created
      summary: A bank account was linked to the seller.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: bank_account.created

    BookingCreated:
      name: booking.created
      title: booking.created
      summary: A booking was created.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.created

    BookingUpdated:
      name: booking.updated
      title: booking.updated
      summary: A booking was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.updated

    BookingCustomAttributeDefinitionOwnedCreated:
      name: booking.custom_attribute_definition.owned.created
      title: booking.custom_attribute_definition.owned.created
      summary: An owned booking custom attribute definition was created.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute_definition.owned.created

    BookingCustomAttributeDefinitionOwnedUpdated:
      name: booking.custom_attribute_definition.owned.updated
      title: booking.custom_attribute_definition.owned.updated
      summary: An owned booking custom attribute definition was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute_definition.owned.updated

    BookingCustomAttributeDefinitionOwnedDeleted:
      name: booking.custom_attribute_definition.owned.deleted
      title: booking.custom_attribute_definition.owned.deleted
      summary: An owned booking custom attribute definition was deleted.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute_definition.owned.deleted

    BookingCustomAttributeOwnedUpdated:
      name: booking.custom_attribute.owned.updated
      title: booking.custom_attribute.owned.updated
      summary: An owned booking custom attribute value was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute.owned.updated

    BookingCustomAttributeOwnedDeleted:
      name: booking.custom_attribute.owned.deleted
      title: booking.custom_attribute.owned.deleted
      summary: An owned booking custom attribute value was deleted.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute.owned.deleted

    BookingCustomAttributeDefinitionVisibleCreated:
      name: booking.custom_attribute_definition.visible.created
      title: booking.custom_attribute_definition.visible.created
      summary: A visible booking custom attribute definition was created.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute_definition.visible.created

    BookingCustomAttributeDefinitionVisibleUpdated:
      name: booking.custom_attribute_definition.visible.updated
      title: booking.custom_attribute_definition.visible.updated
      summary: A visible booking custom attribute definition was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute_definition.visible.updated

    BookingCustomAttributeDefinitionVisibleDeleted:
      name: booking.custom_attribute_definition.visible.deleted
      title: booking.custom_attribute_definition.visible.deleted
      summary: A visible booking custom attribute definition was deleted.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute_definition.visible.deleted

    BookingCustomAttributeVisibleUpdated:
      name: booking.custom_attribute.visible.updated
      title: booking.custom_attribute.visible.updated
      summary: A visible booking custom attribute value was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute.visible.updated

    BookingCustomAttributeVisibleDeleted:
      name: booking.custom_attribute.visible.deleted
      title: booking.custom_attribute.visible.deleted
      summary: A visible booking custom attribute value was deleted.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: booking.custom_attribute.visible.deleted

    CardAutomaticallyUpdated:
      name: card.automatically_updated
      title: card.automatically_updated
      summary: A card on file was automatically updated by the network.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: card.automatically_updated

    CardCreated:
      name: card.created
      title: card.created
      summary: A card on file was created.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: card.created

    CardDisabled:
      name: card.disabled
      title: card.disabled
      summary: A card on file was disabled.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: card.disabled

    CardForgotten:
      name: card.forgotten
      title: card.forgotten
      summary: A card on file was forgotten (data removed).
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: card.forgotten

    CardUpdated:
      name: card.updated
      title: card.updated
      summary: A card on file was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: card.updated

    CatalogVersionUpdated:
      name: catalog.version.updated
      title: catalog.version.updated
      summary: The seller's catalog version changed.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: catalog.version.updated

    OnlineCheckoutLocationSettingsUpdated:
      name: online_checkout.location_settings.updated
      title: online_checkout.location_settings.updated
      summary: Online checkout location settings were updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: online_checkout.location_settings.updated

    OnlineCheckoutMerchantSettingsUpdated:
      name: online_checkout.merchant_settings.updated
      title: online_checkout.merchant_settings.updated
      summary: Online checkout merchant settings were updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: online_checkout.merchant_settings.updated

    CustomerCreated:
      name: customer.created
      title: customer.created
      summary: A customer was created.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.created

    CustomerDeleted:
      name: customer.deleted
      title: customer.deleted
      summary: A customer was deleted.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.deleted

    CustomerUpdated:
      name: customer.updated
      title: customer.updated
      summary: A customer was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.updated

    CustomerCustomAttributeDefinitionOwnedCreated:
      name: customer.custom_attribute_definition.owned.created
      title: customer.custom_attribute_definition.owned.created
      summary: An owned customer custom attribute definition was created.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.custom_attribute_definition.owned.created

    CustomerCustomAttributeDefinitionOwnedUpdated:
      name: customer.custom_attribute_definition.owned.updated
      title: customer.custom_attribute_definition.owned.updated
      summary: An owned customer custom attribute definition was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.custom_attribute_definition.owned.updated

    CustomerCustomAttributeDefinitionOwnedDeleted:
      name: customer.custom_attribute_definition.owned.deleted
      title: customer.custom_attribute_definition.owned.deleted
      summary: An owned customer custom attribute definition was deleted.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.custom_attribute_definition.owned.deleted

    CustomerCustomAttributeOwnedUpdated:
      name: customer.custom_attribute.owned.updated
      title: customer.custom_attribute.owned.updated
      summary: An owned customer custom attribute value was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.custom_attribute.owned.updated

    CustomerCustomAttributeOwnedDeleted:
      name: customer.custom_attribute.owned.deleted
      title: customer.custom_attribute.owned.deleted
      summary: An owned customer custom attribute value was deleted.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.custom_attribute.owned.deleted

    CustomerCustomAttributeDefinitionVisibleCreated:
      name: customer.custom_attribute_definition.visible.created
      title: customer.custom_attribute_definition.visible.created
      summary: A visible customer custom attribute definition was created.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.custom_attribute_definition.visible.created

    CustomerCustomAttributeDefinitionVisibleUpdated:
      name: customer.custom_attribute_definition.visible.updated
      title: customer.custom_attribute_definition.visible.updated
      summary: A visible customer custom attribute definition was updated.
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/SquareWebhookHeaders'
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties:
              type:
                const: customer.custom_attribute_definition.visible.updated

    CustomerCustomAttributeDefinitionVisibleDeleted:
      name: customer.custom_attribute_definition.visible.deleted
 

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/square/refs/heads/main/asyncapi/square-webhooks-asyncapi.yml