Square Webhooks Overview
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 60 webhook events you can subscribe to. A subscription can have many events. 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.
Webhooks from Square originate from the following IP addresses. These are provided so you can allow access by these addresses through a firewall you are using.
Production IP addresses:
Sandbox IP addresses:
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 webhook events that you want to subscribe to.
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 of event notices.
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 Square does not attempt to resend the notification.
Square uses exponential backoff to avoid spamming applications and retries notifications according to the following schedule. For example, if Square doesn't receive a 2xx status code 10 seconds after the event notice is received, then Square will send another notice of the event in one minute. If no 2xx status code is received in 19 seconds, Square tries again to send the event notice in two minutes. The retry pattern is shown below:
|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:
Cash Drawer API
Mobile Authorization API
Customer Groups API
Customer Segments API
Apple Pay API
When your application is ready to be moved from the Sandbox environment to production, there are several things you need to do to manage webhook event notifications in production. These include:
Get production application credentials. In the Developer Dashboard, open your application. Select Production on the environment toggle at the top of the page. In the navigation pane select Credentials, then copy the production application ID and the production access token.
Enter production subscription information. In the navigation pane, select Webhooks, then select Subscriptions. Select Add subscription and enter the webhook event subscription name and the production notification URL, select the API version, and select only the events your application needs. Select Save.
Replace your Sandbox access token and application ID with production values in your application.
Update your code to make API calls to Square production endpoints.
Use idempotency. A generated idempotency value is included as the event_id field in the body of each event notification. Design your application to use this value to bypass processing if it is a repeated value.
Use message versioning. If your application passes Square data to another application, you should add versioning to the data before passing it to avoid duplication and to make auditing of the data transfer easier.
Validate the webhook event notification. A non-Square post can potentially compromise your application. All webhook notifications from Square include an x-square-signature header. The value of this header is an HMAC-SHA256 signature generated using your webhook signature key, the notification URL, and the raw body of the request. You can validate the webhook notification by generating the HMAC-SHA256 in your own code and comparing it to the signature of the event notification you received. For more information and code examples that show how to validate the signature of an event notification, see Verify and Validate an Event Notification.