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 a list of event types to be notified about. When an event occurs, Square collects data about the event, creates an event notification, and sends it to the notification URL for all webhook subscriptions that are subscribed to that event. Your application must respond with a 2xx status code as soon as possible to acknowledge that the notification was received.

Events can originate from the Square Dashboard, a Point of Sale (POS) application, other Square products, and third-party applications calling Square APIs. For each event occurrence, Square sends a POST request to your notification URL with the event details in JSON format.

You can use webhooks to trigger additional events when an event occurs and integrate with external systems. For example:

• Send email notifications when an event occurs, such as:
  • A refund is more than a certain limit.
  • The inventory for an item is getting too low.
  • A high-value item was sold.
• Pass data to another system after an event, such as sending customer data to a CRM.
• Connect a third-party POS system to a Square Terminal.
• Trigger other applications to respond to an event.

Before you start:

• Define a notification URL that points to your application - This is 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.
• Determine the Square API events that you want to subscribe to - This is the set of webhook events that trigger an event notification for your application.

Applications need at least one reachable notification URL to receive and process webhook events from Square. The notification URL endpoint must:

• Require a connection that uses HTTPS.

• Expect JSON data from a POST request.

• Respond to Square with a 2xx HTTP status code 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 and your application has 10 seconds to respond.

  Notification URLs are specified on the Webhook subscriptions page for your application in the Developer Console or using the 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 response with a 2xx HTTP status code isn't received in a timely manner or if any other status code is returned, Square assumes that the delivery is unsuccessful and starts retry attempts. Square resends the event notification for up to 48 hours after the originating event, using exponential backoff to avoid spamming applications. After 48 hours, the notification is discarded and no further retry attempts are made.

The retry schedule is as follows:

For example, if a 2xx status code isn't received in a timely manner after the initial event notification, Square resends the notification after 1 minute (retry attempt 1). If a 2xx status code isn't received in a timely manner, Square resends the notification after 2 minutes (retry attempt 2). Retried notifications include the square-retry-number and square-retry-reason headers. For more information, see Format of an event notification.

The following Square APIs don't support webhooks:

• Snippets API
• Sites API
• Merchants API
• Cash Drawer Shifts 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