Square Webhooks

Learn about Square webhooks, which let developers receive real-time notifications of events, such as inventory changes and Point of Sale payments.

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 hundreds of webhook events you can subscribe to. A subscription can have many events. Events can originate from the Square 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 more than 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 do the following:

• Expect JSON data from a POST request and respond with a 2xx HTTP status code to Square as soon as possible to acknowledge the successful receipt of the event notification. If your application fails to acknowledge the notification in a timely manner, a duplicate event is sent that your application has 10 seconds to respond to.

Webhooks can be sent more than once. You can bypass the processing of repeated notifications using the idempotency value included as the event_id field in the body of each event notification.

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 Console.

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

Before you start:

• Define a URL that points to your application - Define an endpoint that directs webhook event notifications to your application.
• Determine the 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 in a timely manner to acknowledge the receipt of the event notification.
• The URL endpoint must require that a connection uses HTTPS.
• You can create the webhook event subscription using the Developer Console or Webhook Subscriptions API.

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's no guarantee of the delivery order of event notices.

Webhooks from Square originate from the following IP addresses. These are provided so you can allow access by these addresses through a firewall you're using.

Production IP addresses:

• 54.245.1.154
• 34.202.99.168

Sandbox IP addresses:

• 54.212.177.79
• 107.20.218.8

If a 2xx HTTP status code isn't received in a timely manner or a status code other than 2xx is returned, Square assumes that the delivery is 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 doesn't 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 in a timely manner after the event notification is sent, Square sends another notification of the event in 1 minute. If no 2xx status code is received in a timely manner, Square tries again to send the event notification in 2 minutes. The retry pattern is as follows:

The following Square APIs don't support webhooks:

• Snippets API
• Sites API
• Merchants API
• Cash Drawer API
• Mobile Authorization API
• Customer Groups API
• Customer Segments API
• Apple Pay API

• Create a Notification URL
• Subscribe to Event Notifications
• Verify and Validate an Event Notification
• Manage Webhook Operations
• Webhook Subscriptions API
• Video: Webhooks