Verify and Validate an Event Notification

Learn about the third step for setting up Square webhooks, which is to verify that you receive the event notification and validate that the notification originated from Square.

Link to section

Verify that you receive a notification

You can verify the creation and receipt of an event notification using either a test endpoint you create or a public site such as webhook.site. You can use API Explorer to generate events that webhooks can subscribe to.

To verify your event notification subscription using webhook.site:

  1. Go to webhook.site in a browser, copy the provided unique URL to the clipboard, and leave the page open.
  2. Create a webhook subscription by following the steps in Subscribe to Event Notifications. For testing purposes, choose Select All under Events.
  3. Enter the unique URL you copied from webhook.site as your notification URL.
  4. Trigger an event from API Explorer. For example, generate a customer.created event by calling the CreateCustomer endpoint in the Customers API and providing a given name (first name), family name (last name), company name, email address, or phone number.
  5. Return to the webhook.site page to view the event notification.

After you verify that your webhook subscription is working, you need to add code to your notification URL so that your application can process the event.

Link to section

Validate that the notification is from Square

Your notification URL is public and can be called by anyone, so you must validate each event notification to confirm that it originated from Square. A non-Square post can potentially compromise your application.

All webhook notifications from Square include an x-square-hmacsha256-signature header. The value of this header is an HMAC-SHA-256 signature generated using your webhook signature key, the notification URL, and the raw body of the request. To validate the webhook notification, generate the HMAC-SHA-256 value in your own code and compare it to the signature of the event notification you received.

Important

A malicious agent can compromise your notification endpoint by using a timing analysis attack to determine the key you're using to decrypt and compare webhook signatures. You should use a constant-time crypto library to prevent such attacks by masking the actual time taken to decrypt and compare signatures.

Link to section

Validation examples

The following functions generate an HMAC-SHA256 signature from your signature key, the notification URL, and the event notification body. The generated signature is compared with the event notification's x-square-hmacsha256-signature.

Important

When testing your webhook event notifications, make sure to use the raw request body without any whitespace. For example, {"hello":"world"}.

Link to section

Node.js

Link to section

Python

Link to section

C#

Link to section

Go

Link to section

Java

Link to section

PHP

Link to section

Ruby