Square Webhooks

A webhook is a subscription that registers a notification URL and the events that you want to be notified about. When an event occurs, Square collects data about the event, creates an event notification, and sends the event notification to the notification URL for all webhook subscriptions that are subscribed to the event.

There are more than 50 webhook events you can subscribe to. Events can originate from the Seller Dashboard or a Point of Sale (POS) application or from calling an API endpoint from a third-party application. For each event occurrence, Square sends a POST request to your notification URL with the event details in JSON format.

A few ways you can use webhooks include:

  • Creating email notifications when an event occurs:

    • If a refund is above a certain limit.

    • If the inventory for an item is getting too low.

    • If a high-value item has sold.

  • Passing data to another system after an event, such as sending customer data to a CRM.

  • Connecting a third-party POS system to a Square Terminal.

  • Triggering additional events when an event occurs.

  • Triggering other applications to respond to an event.

The notification URL must expect JSON data from a POST request and confirm the successful receipt of that data. Applications need at least one reachable notification URL to receive and process webhook events from Square. Notification URLs are specified on the Webhooks page of your application in the Developer Dashboard.

For a list of all Square API events that you can subscribe to, see V2 Webhook Events Technical Reference.

Before you start Permalink Get a link to this section

  • Define a URL that points to your application. Define an endpoint that will direct webhook event notifications to your application.

  • Determine a Square API version. The API version you select must include the events that you want to subscribe to.

Requirements and limitations Permalink Get a link to this section

The notification URL must do the following:

  • Respond with a 2xx HTTP status code to Square within 10 seconds to acknowledge the receipt of the event notification.

  • The URL endpoint must require that a connection use HTTPS.

  • You must create the webhook event subscription using the Developer Dashboard.

Square provides the following SLA for webhook event notifications:

  • In most cases, event notifications arrive in well under 60 seconds of the associated event.

  • There is no guarantee of the delivery order.

  • If a 2xx HTTP status code is not received within 10 seconds or a status code other than 2xx is returned, Square assumes that the delivery was unsuccessful. Square retries the delivery of the event notification using exponential backoff for up to 72 hours after the originating event. After 72 hours, the notification is discarded and not sent again.

Square uses exponential backoff to avoid spamming applications and retries notifications according to the following schedule:

Retry attempt Time between attempts Time since webhook event
1 1 minute 1 minute
2 2 minutes 3 minutes
3 4 minutes 7 minutes
4 8 minutes 15 minutes
5 16 minutes 31 minutes
6 32 minutes 63 minutes
7 – 78 60 minutes 2 – 72 hours

The following Square APIs do not support webhooks:

  • Snippets API

  • Sites API

  • Merchants API

  • Cash Drawer API

  • Mobile Authorization API

  • Customer Groups API

  • Customer Segments API

  • Apple Pay API

  • Checkout API

Related topics Permalink Get a link to this section