Manage Webhook Operations

There are two aspects of Square webhook events that you need to understand: when events are triggered in a transaction and how to manage event notifications.

Link to section

Understand when events are triggered

Events that you can subscribe to using webhooks are generated by the various Square applications and Square APIs. For example, during a sales transaction, several events could be generated including an updated customer record and inventory adjustment along with an invoice creation.

Link to section

Manage event notifications

When your notification URL endpoint receives an event notification, you must respond in a timely manner to the POST request and store the event information securely.

Cloud-based serverless applications, microservices, and function as a service (FaaS) applications let you handle event notifications without setting up a server. The Sandbox 101: Implementing Webhooks video shows how to create a serverless application on Amazon Web Services that responds to event notifications and stores the data for later retrieval. It includes sample code on GitHub. For more information about using FaaS applications with Square webhook event notifications, see the blog post Stop Using Servers to Handle Webhooks.

Link to section

Disable failed webhooks

If your notification URL endpoint doesn't respond with a single 2xx HTTP status code within three weeks, Square takes the following actions:

  1. Sends a warning email after the first week.
  2. Sends a warning email after the second week.
  3. Sends a final warning email after the third week.

Following this final email, Square automatically disables your webhook subscription.

To diagnose issues with your webhook subscription, see Troubleshoot Webhooks.

Link to section

Webhooks best practices

  • 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's 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.
Link to section

See also