v1 Webhooks

Validate Notifications

Validate v1 Webhook event notifications.

Webhooks API

Once you are sure your webhooks are working, you will need to add code to your notification URL so that your application does something with the events it receives. We recommend validating webhook notifications to confirm they came from Square. While not strictly required, validating the sender adds an extra layer of security and helps avoid man-in-the-middle attacks.

Prerequisites and assumptions
Permalink Get a link to this section


This guide also makes the following assumptions:

  • You are familiar with basic web development. If you are new to web development, we recommend reading Getting started with the Web by Mozilla.org before continuing.

  • You can create and run websites on localhost or a development server. If you are new to testing webpages locally, we recommend reading Running Local Web Servers before continuing.

  • You have read the What It Does page for this product.

  • You are subscribed to at least 1 v1 webhook event.

Information you will need
Permalink Get a link to this section

To use the steps in this guide you will need the following information:

  • The webhook signature key assigned in the Webhooks settings page for your application.

v1 Webhook signature key

Step 1: Get notification signature
Permalink Get a link to this section

All webhook notifications from Square include an X-Square-Signature header. The value of this header is an HMAC-SHA1 signature generated using your webhook notification URL and the body of the request excluding all whitespace.

$notificationSignature = getallheaders()['X-Square-Signature'];

Step 2: Create a function to validate the signature
Permalink Get a link to this section

You can validate the webhook notification by generating the HMAC-SHA1 in your own code and comparing it to the signature of the notification you received. The example function below generates an HMAC-SHA1 signature from your notification URL and the notification body, then compares it with the provided signature.


The value of $webhookSignatureKey is the Signature Key assigned by the Square Application Dashboard in the Webhooks settings page for your application.

function isValidSignature($notificationBody, $notificationSignature, $notificationUrl, $webhookSignatureKey) {

  // Concatenate your notification URL and
  // the JSON body of the webhook notification
  $stringToSign = $webhookUrl . $notificationBody;

  // Generate the HMAC-SHA1 signature of the string
  // signed with your webhook signature key
  $stringSignature = base64_encode(hash_hmac(
                        'sha1',
                        $stringToSign,
                        $webhookSignatureKey,
                        true));

  // Compare HMAC-SHA1 signatures.
  if (hash_equals($stringSignature, $notificationSignature)) {
    echo "Hashes match!";
  }
  else {
    echo "Hashes do not match."
  }
}