Webhooks API

What it Does

Set up real-time notifications for completed transactions and updates to product inventories.

Square Webhooks are HTTP calls or snippets of code that are triggered by specific events. To detect changes to data, typical APIs would require calls at regular time intervals. Square Webhooks replace regular API calls with instant, real-time notifications.

For example, consider a company that works with a manufacturer to print custom images on mugs. This company can use Square Webhooks to send customer images to a manufacturer as soon as a payment is processed.

Product components

A Square Webhook integration includes the following:

  • Events — An action or change in data that generates a notification to be sent to an application.
  • Subscriptions — A request sent to the Webhooks API to receive notifications associated with a specific event.
  • Notification URL — The configurable service in the application to which alerts are sent.
  • Notification body — Details about the event that generated the alert, such as the time it happened or an ID identifying the data that changed.

Events

Events are actions or changes in data that generate notifications. Square Webhooks can be used to create alerts that trigger for these events.

See the technical reference for more information on available webhook events

Subscriptions

Subscribe to webhook notifications by calling the Subscribe endpoint. The Subscribe request body should specify which events the application will subscribe to.

Notification URL

Applications need a notification URL to receive and process webhook events from Square. The notification URL can be set in the Application Dashboard. When trigger events occur, Square Webhooks will send a POST request with event data to that notification URL.

Notification body

Events include the following data:

  • The merchant the event was triggered for.
  • The location where the event occurred.
  • The type of webhook event. See the list of Available webhook events in the Connect Technical Reference for possible values.

PAYMENT_UPDATED notifications also include an entity_id, which is a payment ID that can be used to look up more information.

Notification delivery SLA

Square makes every effort to deliver webhook notifications as quickly as possible. In most cases, notifications will arrive within 60 seconds of the associated event.

Applications must acknowledge the notification by responding within 10 seconds with an HTTP 2xx response code. Responding outside the 10 second window, or with a different HTTP status code (including HTTP 3xx), Square will deem delivery unsuccessful.

Unsuccessful deliveries are retried for up to 72 hours after the originating event. After 72 hours have elapsed, the notification is discarded and will not be sent again. Square uses linear 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

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow