> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Webhook Setup Guide

> Configure Square to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/square#getting-started) on the Square connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Retrieve the StackOne Native Webhook URL</h2>

  <p>The <strong>Native Webhook URL</strong> is generated once a Square account has been linked. Each linked account has its own URL.</p>

  <ul>
    <li>Open the linked account in StackOne.</li>
    <li>Copy the value from <strong>Native Webhook URL</strong>.</li>
  </ul>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Create the webhook subscription in Square</h2>

  <p>Add a webhook subscription to the Square app used by the StackOne Connector profile, so Square posts events to StackOne.</p>

  <Steps>
    <Step title="Sign in to the Square Developer Console">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sign in to your <a href="https://developer.squareup.com/apps" target="_blank" rel="noopener noreferrer">Square Developer account</a>.</p>

        <ul>
          <li>Under <strong>Applications</strong>, find the app whose Application ID is set on the StackOne Connector profile.</li>
          <li>Click <strong>Open</strong>.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/1wgzI52ub_tTDpbT/connectors/square/images/events-setup-open-application.png?fit=max&auto=format&n=1wgzI52ub_tTDpbT&q=85&s=0178aa105123feec0defd0cea9d6f37c" alt="Square Developer Console Applications page with the Open button highlighted on the app card" width="1280" height="800" data-path="connectors/square/images/events-setup-open-application.png" />
      </div>
    </Step>

    <Step title="Open webhook subscriptions">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Select the environment of the linked account, then open the app's webhook subscriptions.</p>

        <ul>
          <li>At the top of the page, select <strong>Sandbox</strong> or <strong>Production</strong>.</li>
          <li>In the left menu, click <strong>Webhooks</strong>, then <strong>Subscriptions</strong>.</li>
          <li>On the <strong>Webhook subscriptions</strong> page, click <strong>Add subscription</strong>.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/1wgzI52ub_tTDpbT/connectors/square/images/events-setup-webhook-subscriptions.png?fit=max&auto=format&n=1wgzI52ub_tTDpbT&q=85&s=78ad7d52770ef173b9e7d0ed4b67c48f" alt="Square app page with the Sandbox and Production toggle and the Webhooks Subscriptions menu item highlighted" width="1280" height="800" data-path="connectors/square/images/events-setup-webhook-subscriptions.png" />
      </div>
    </Step>

    <Step title="Enter the subscription details">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the <strong>Add a webhook subscription</strong> dialog, point the subscription at StackOne.</p>

        <ul>
          <li>Subscription name: `StackOne`</li>
          <li>Paste the Native Webhook URL into <strong>Notification URL</strong>.</li>
          <li>Leave <strong>API version</strong> at its default value.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/1wgzI52ub_tTDpbT/connectors/square/images/events-setup-subscription-details.png?fit=max&auto=format&n=1wgzI52ub_tTDpbT&q=85&s=2882c135a1cb83172d6bd1da91c84760" alt="Add a webhook subscription dialog with the Subscription name and Notification URL fields highlighted" width="1280" height="800" data-path="connectors/square/images/events-setup-subscription-details.png" />
      </div>
    </Step>

    <Step title="Select events and save">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Under <strong>Events</strong>, choose which events Square sends to StackOne.</p>

        <ul>
          <li>Use <strong>Search</strong> to find each event you want, for example `payment.created`, and tick its checkbox.</li>
          <li>Tick only events listed in Available webhook events below. Other events are acknowledged and dropped.</li>
          <li>Click <strong>Save</strong>.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/1wgzI52ub_tTDpbT/connectors/square/images/events-setup-select-events.png?fit=max&auto=format&n=1wgzI52ub_tTDpbT&q=85&s=2bc7cdac070f784a0ab2dd22e606158b" alt="Events list filtered by payment with payment.created and payment.updated ticked and the Save button highlighted" width="1280" height="800" data-path="connectors/square/images/events-setup-select-events.png" />
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following Square events can be received. Each event's record ID is the Square ID of the affected record (data.id), or Square's event ID when the event has no record. The event data holds the full Square event, including the affected object.</p>

  <Steps>
    <Step title="Payments events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for payments.</p>

        <ul>
          <li><strong>Payment Created</strong> (`payment.created`) — Fired when a payment is created.</li>
          <li><strong>Payment Updated</strong> (`payment.updated`) — Fired when a payment field changes, such as status or card\_details.status.</li>
        </ul>
      </div>
    </Step>

    <Step title="Refunds events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for refunds.</p>

        <ul>
          <li><strong>Refund Created</strong> (`refund.created`) — Fired when a refund is created.</li>
          <li><strong>Refund Updated</strong> (`refund.updated`) — Fired when a refund is updated, typically when its status changes on completion.</li>
        </ul>
      </div>
    </Step>

    <Step title="Cards events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for cards.</p>

        <ul>
          <li><strong>Card Created</strong> (`card.created`) — Fired when a card on file is created or imported.</li>
          <li><strong>Card Automatically Updated</strong> (`card.automatically_updated`) — Fired when Square automatically updates a card expiration date or PAN, or adds or removes an issuer alert.</li>
          <li><strong>Card Updated</strong> (`card.updated`) — Fired when the seller updates a card in the Square Dashboard.</li>
          <li><strong>Card Disabled</strong> (`card.disabled`) — Fired when a card on file is disabled.</li>
          <li><strong>Card Forgotten</strong> (`card.forgotten`) — Fired when a card is GDPR forgotten or vaulted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Disputes events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for disputes.</p>

        <ul>
          <li><strong>Dispute Created</strong> (`dispute.created`) — Fired when a dispute is created.</li>
          <li><strong>Dispute State Updated</strong> (`dispute.state.updated`) — Fired when the state of a dispute changes, including the WON or LOST resolution reported by the bank.</li>
          <li><strong>Dispute Evidence Created</strong> (`dispute.evidence.created`) — Fired when evidence is added to a dispute.</li>
          <li><strong>Dispute Evidence Deleted</strong> (`dispute.evidence.deleted`) — Fired when evidence is removed from a dispute.</li>
        </ul>
      </div>
    </Step>

    <Step title="Payouts events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for payouts.</p>

        <ul>
          <li><strong>Payout Sent</strong> (`payout.sent`) — Fired when a payout is sent.</li>
          <li><strong>Payout Paid</strong> (`payout.paid`) — Fired when a payout is completed.</li>
          <li><strong>Payout Failed</strong> (`payout.failed`) — Fired when a payout fails.</li>
        </ul>
      </div>
    </Step>

    <Step title="Bank Accounts events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for bank accounts.</p>

        <ul>
          <li><strong>Bank Account Created</strong> (`bank_account.created`) — Fired when a bank account is linked to the Square account.</li>
          <li><strong>Bank Account Verified</strong> (`bank_account.verified`) — Fired when Square sets the status of a bank account to VERIFIED.</li>
          <li><strong>Bank Account Disabled</strong> (`bank_account.disabled`) — Fired when Square sets the status of a bank account to DISABLED.</li>
        </ul>
      </div>
    </Step>

    <Step title="Gift Cards events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for gift cards.</p>

        <ul>
          <li><strong>Gift Card Created</strong> (`gift_card.created`) — Fired when a digital gift card is created or a physical gift card is registered.</li>
          <li><strong>Gift Card Updated</strong> (`gift_card.updated`) — Fired when the balance, state or linked customers of a gift card change.</li>
          <li><strong>Gift Card Customer Linked</strong> (`gift_card.customer_linked`) — Fired when a customer is linked to a gift card.</li>
          <li><strong>Gift Card Customer Unlinked</strong> (`gift_card.customer_unlinked`) — Fired when a customer is unlinked from a gift card.</li>
          <li><strong>Gift Card Activity Created</strong> (`gift_card.activity.created`) — Fired when a gift card activity is created.</li>
          <li><strong>Gift Card Activity Updated</strong> (`gift_card.activity.updated`) — Fired when a REDEEM or IMPORT gift card activity is updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Orders events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for orders.</p>

        <ul>
          <li><strong>Order Created</strong> (`order.created`) — Fired when an order is created by a Square product or an application.</li>
          <li><strong>Order Updated</strong> (`order.updated`) — Fired when an order is updated through UpdateOrder or by the seller.</li>
          <li><strong>Order Fulfillment Updated</strong> (`order.fulfillment.updated`) — Fired when an order fulfillment is created or updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Invoices events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for invoices.</p>

        <ul>
          <li><strong>Invoice Created</strong> (`invoice.created`) — Fired when a draft invoice is created.</li>
          <li><strong>Invoice Updated</strong> (`invoice.updated`) — Fired when an invoice changes, including after it is published or canceled.</li>
          <li><strong>Invoice Published</strong> (`invoice.published`) — Fired when an invoice is published, including invoices scheduled for later processing.</li>
          <li><strong>Invoice Payment Made</strong> (`invoice.payment_made`) — Fired when a payment is made for an invoice.</li>
          <li><strong>Invoice Scheduled Charge Failed</strong> (`invoice.scheduled_charge_failed`) — Fired when a scheduled automatic invoice payment fails.</li>
          <li><strong>Invoice Canceled</strong> (`invoice.canceled`) — Fired when an invoice is canceled.</li>
          <li><strong>Invoice Refunded</strong> (`invoice.refunded`) — Fired when a refund is processed for an invoice.</li>
          <li><strong>Invoice Deleted</strong> (`invoice.deleted`) — Fired when a draft invoice is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Subscriptions events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for subscriptions.</p>

        <ul>
          <li><strong>Subscription Created</strong> (`subscription.created`) — Fired when a subscription is created.</li>
          <li><strong>Subscription Updated</strong> (`subscription.updated`) — Fired when a subscription is updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Catalog events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for catalog.</p>

        <ul>
          <li><strong>Catalog Version Updated</strong> (`catalog.version.updated`) — Fired when the catalog is updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Inventory events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for inventory.</p>

        <ul>
          <li><strong>Inventory Count Updated</strong> (`inventory.count.updated`) — Fired when the quantity of a catalog item variation changes.</li>
        </ul>
      </div>
    </Step>

    <Step title="Customers events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for customers.</p>

        <ul>
          <li><strong>Customer Created</strong> (`customer.created`) — Fired when a customer profile is created, including when profiles are merged.</li>
          <li><strong>Customer Updated</strong> (`customer.updated`) — Fired when an attribute on a customer profile changes, except segment\_ids.</li>
          <li><strong>Customer Deleted</strong> (`customer.deleted`) — Fired when a customer profile is deleted, including when profiles are merged.</li>
        </ul>
      </div>
    </Step>

    <Step title="Locations events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for locations.</p>

        <ul>
          <li><strong>Location Created</strong> (`location.created`) — Fired when a location is created.</li>
          <li><strong>Location Updated</strong> (`location.updated`) — Fired when a location is updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Checkout events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for checkout.</p>

        <ul>
          <li><strong>Online Checkout Location Settings Updated</strong> (`online_checkout.location_settings.updated`) — Fired when online checkout location settings are updated.</li>
          <li><strong>Online Checkout Merchant Settings Updated</strong> (`online_checkout.merchant_settings.updated`) — Fired when online checkout merchant settings are updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Team Members events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for team members.</p>

        <ul>
          <li><strong>Team Member Created</strong> (`team_member.created`) — Fired when a team member is created.</li>
          <li><strong>Team Member Updated</strong> (`team_member.updated`) — Fired when a team member is updated.</li>
          <li><strong>Team Member Wage Setting Updated</strong> (`team_member.wage_setting.updated`) — Fired when the wage setting of a team member is updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Jobs events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for jobs.</p>

        <ul>
          <li><strong>Job Created</strong> (`job.created`) — Fired when a job is created.</li>
          <li><strong>Job Updated</strong> (`job.updated`) — Fired when a job is updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Timecards events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for timecards.</p>

        <ul>
          <li><strong>Timecard Created</strong> (`labor.timecard.created`) — Fired when a timecard is created at the start of a shift.</li>
          <li><strong>Timecard Updated</strong> (`labor.timecard.updated`) — Fired when a timecard is updated.</li>
          <li><strong>Timecard Deleted</strong> (`labor.timecard.deleted`) — Fired when a timecard is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Scheduled Shifts events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for scheduled shifts.</p>

        <ul>
          <li><strong>Scheduled Shift Created</strong> (`labor.scheduled_shift.created`) — Fired when a scheduled shift is created.</li>
          <li><strong>Scheduled Shift Updated</strong> (`labor.scheduled_shift.updated`) — Fired when a scheduled shift is updated.</li>
          <li><strong>Scheduled Shift Published</strong> (`labor.scheduled_shift.published`) — Fired when a scheduled shift is published.</li>
          <li><strong>Scheduled Shift Deleted</strong> (`labor.scheduled_shift.deleted`) — Fired when a scheduled shift is permanently deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Authorization events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for authorization.</p>

        <ul>
          <li><strong>OAuth Authorization Revoked</strong> (`oauth.authorization.revoked`) — Fired when the seller revokes all access and refresh tokens granted to the application.</li>
        </ul>
      </div>
    </Step>

    <Step title="Custom Attributes events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for custom attributes.</p>

        <ul>
          <li><strong>Customer Custom Attribute Definition Owned Created</strong> (`customer.custom_attribute_definition.owned.created`) — Fired when a customer custom attribute definition owned by the application is created.</li>
          <li><strong>Customer Custom Attribute Definition Owned Updated</strong> (`customer.custom_attribute_definition.owned.updated`) — Fired when a customer custom attribute definition owned by the application is updated.</li>
          <li><strong>Customer Custom Attribute Definition Owned Deleted</strong> (`customer.custom_attribute_definition.owned.deleted`) — Fired when a customer custom attribute definition owned by the application is deleted.</li>
          <li><strong>Customer Custom Attribute Owned Updated</strong> (`customer.custom_attribute.owned.updated`) — Fired when a customer custom attribute owned by the application is created or updated.</li>
          <li><strong>Customer Custom Attribute Owned Deleted</strong> (`customer.custom_attribute.owned.deleted`) — Fired when a customer custom attribute owned by the application is deleted.</li>
          <li><strong>Customer Custom Attribute Definition Visible Created</strong> (`customer.custom_attribute_definition.visible.created`) — Fired when a customer custom attribute definition visible to the application is created.</li>
          <li><strong>Customer Custom Attribute Definition Visible Updated</strong> (`customer.custom_attribute_definition.visible.updated`) — Fired when a customer custom attribute definition visible to the application is updated.</li>
          <li><strong>Customer Custom Attribute Definition Visible Deleted</strong> (`customer.custom_attribute_definition.visible.deleted`) — Fired when a customer custom attribute definition visible to the application is deleted.</li>
          <li><strong>Customer Custom Attribute Visible Updated</strong> (`customer.custom_attribute.visible.updated`) — Fired when a customer custom attribute visible to the application is created or updated.</li>
          <li><strong>Customer Custom Attribute Visible Deleted</strong> (`customer.custom_attribute.visible.deleted`) — Fired when a customer custom attribute visible to the application is deleted.</li>
          <li><strong>Booking Custom Attribute Definition Owned Created</strong> (`booking.custom_attribute_definition.owned.created`) — Fired when a booking custom attribute definition owned by the application is created.</li>
          <li><strong>Booking Custom Attribute Definition Owned Updated</strong> (`booking.custom_attribute_definition.owned.updated`) — Fired when a booking custom attribute definition owned by the application is updated.</li>
          <li><strong>Booking Custom Attribute Definition Owned Deleted</strong> (`booking.custom_attribute_definition.owned.deleted`) — Fired when a booking custom attribute definition owned by the application is deleted.</li>
          <li><strong>Booking Custom Attribute Owned Updated</strong> (`booking.custom_attribute.owned.updated`) — Fired when a booking custom attribute owned by the application is created or updated.</li>
          <li><strong>Booking Custom Attribute Owned Deleted</strong> (`booking.custom_attribute.owned.deleted`) — Fired when a booking custom attribute owned by the application is deleted.</li>
          <li><strong>Booking Custom Attribute Definition Visible Created</strong> (`booking.custom_attribute_definition.visible.created`) — Fired when a booking custom attribute definition visible to the application is created.</li>
          <li><strong>Booking Custom Attribute Definition Visible Updated</strong> (`booking.custom_attribute_definition.visible.updated`) — Fired when a booking custom attribute definition visible to the application is updated.</li>
          <li><strong>Booking Custom Attribute Definition Visible Deleted</strong> (`booking.custom_attribute_definition.visible.deleted`) — Fired when a booking custom attribute definition visible to the application is deleted.</li>
          <li><strong>Booking Custom Attribute Visible Updated</strong> (`booking.custom_attribute.visible.updated`) — Fired when a booking custom attribute visible to the application is created or updated.</li>
          <li><strong>Booking Custom Attribute Visible Deleted</strong> (`booking.custom_attribute.visible.deleted`) — Fired when a booking custom attribute visible to the application is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Bookings events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for bookings.</p>

        <ul>
          <li><strong>Booking Created</strong> (`booking.created`) — Fired when a booking is created.</li>
          <li><strong>Booking Updated</strong> (`booking.updated`) — Fired when a booking is updated or canceled, through the API, the Square Dashboard or the seller booking site.</li>
        </ul>
      </div>
    </Step>

    <Step title="Loyalty events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for loyalty.</p>

        <ul>
          <li><strong>Loyalty Account Created</strong> (`loyalty.account.created`) — Fired when a loyalty account is created for a buyer.</li>
          <li><strong>Loyalty Account Updated</strong> (`loyalty.account.updated`) — Fired when a loyalty account is updated, for example its phone number or point balance.</li>
          <li><strong>Loyalty Account Deleted</strong> (`loyalty.account.deleted`) — Fired when a loyalty account is deleted.</li>
          <li><strong>Loyalty Event Created</strong> (`loyalty.event.created`) — Fired when a balance-changing loyalty event occurs, such as points accumulated or a reward redeemed.</li>
          <li><strong>Loyalty Program Created</strong> (`loyalty.program.created`) — Fired when a loyalty program is created in the Square Dashboard.</li>
          <li><strong>Loyalty Program Updated</strong> (`loyalty.program.updated`) — Fired when a loyalty program is updated in the Square Dashboard.</li>
          <li><strong>Loyalty Promotion Created</strong> (`loyalty.promotion.created`) — Fired when a loyalty promotion is created.</li>
          <li><strong>Loyalty Promotion Updated</strong> (`loyalty.promotion.updated`) — Fired when a loyalty promotion is updated, for example canceled.</li>
        </ul>
      </div>
    </Step>

    <Step title="Terminal events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for terminal.</p>

        <ul>
          <li><strong>Terminal Checkout Created</strong> (`terminal.checkout.created`) — Fired when a Terminal checkout request is created.</li>
          <li><strong>Terminal Checkout Updated</strong> (`terminal.checkout.updated`) — Fired when the status of a Terminal checkout changes.</li>
          <li><strong>Terminal Refund Created</strong> (`terminal.refund.created`) — Fired when a Terminal refund request is created.</li>
          <li><strong>Terminal Refund Updated</strong> (`terminal.refund.updated`) — Fired when the status of a Terminal refund changes.</li>
        </ul>
      </div>
    </Step>

    <Step title="Devices events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for devices.</p>

        <ul>
          <li><strong>Device Code Paired</strong> (`device.code.paired`) — Fired when a Square Terminal is paired with a Terminal API device code.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Square delivers events to StackOne.</p>

  <Steps>
    <Step title="One event per request">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Square sends one event per request. If StackOne does not answer with a 2xx status, Square retries the event with exponential backoff for up to 24 hours, so the same event (same event ID) can arrive more than once.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.