Resources

Build with Webhooks

Subscribe to Square Webhooks and validate notifications.

Prerequisites

You must have a Square account to use Square Webhooks. Create a Square account in minutes if you don't already have one.

Assumptions

  • You have read Webhooks What it Does for an overview of how Square Webhooks work.
  • You are familiar with HTTP, cURL, and PHP.

Step 1: Subscribe to Square Webhook notifications

To initialize your webhook listener, you need to subscribe to the events you want notifications for. You only need to do this once.

The quickest way to subscribe to webhook events is to use the following cURL command:

curl -X PUT                                        \
-H "Authorization: Bearer ACCESS_TOKEN"          \
-H "Content-Type: application/json"              \
-d '[EVENT_LIST]'                                \
https://connect.squareup.com/v1/LOCATION_ID/webhooks

To subscribe using cURL:

  1. Replace ACCESS_TOKEN with the access token for the account being targeted.

  2. Replace LOCATION_ID with a valid location ID for the account being targeted.

  3. Replace EVENT_LIST with a comma-separated list of the notification events you want to subscribe to. EVENT_LIST uses the following syntax:

    ["PAYMENT_UPDATED", "INVENTORY_UPDATED"]
    

    See the list of Available webhook events in the Connect Technical Reference for possible values.

  4. Open the Mac Terminal or Windows Command Prompt. Then, enter the cURL command. If the subscription request is successful, you will receive an array with all the webhook notifications you are now subscribed to.

Step 2: Set up notification URL in your application dashboard

Step 2.A: Set notification URL in the Dashboard

  1. Go to the Dashboard.
  2. Click on the app you want to enable webhooks for. Then, click on the Webhooks tab.
  3. Click enable Webhooks.
  4. Add a link to your notification URL

Step 2.B: Add code that validates webhook notifications

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.

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.

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 value of $webhookSignatureKey is the Signature Key assigned by the Square Application Dashboard in the Webhooks settings page for your application.

  1. Get the notification signature:
$notificationSignature = getallheaders()['X-Square-Signature'];
  1. Create a function to validate the signature. The example function below generates an HMAC-SHA1 signature from your notification URL and the notification body, then compares it with the provided signature.
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."
  }
}

Optional: Test your webhook events with a test webhooks listener

You can test your webhook subscriptions using webhook.site to make sure they are sending events before you finish setting up your notification URL.

  1. In a new tab, go to https://webhook.site and create a subdomain. It will automatically generate a notification URL for you to use. Copy the URL.
  2. Go to the Application Dashboard and click the application you want to work with. Select the Webhooks tab.
  3. Click Enable Webhooks if it is not already enabled.
  4. In the Notification URL field, paste the URL you received from webhook.site.
  5. Click Save.

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