Manage Webhook Operations

Learn about the final step to creating Square webhooks, which is to have your application safely process and store the event information.

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.

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.

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.

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.

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

• Create a Notification URL
• Subscribe to Event Notifications
• Verify and Validate an Event Notification
• Video: Webhooks