Webhooks

Step 3: Verify and Validate an Event 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. For more information about using API Explorer, see Testing with API Explorer.

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 using Step 2: Subscribe to Event Notifications.

  3. Use the unique URL you copied from webhook.site for your notification URL, and then choose Select All under Events.

  4. Create an event in API Explorer. Creating a customer using the Customers API is a simple way to create an event because it requires only one of the five identity values, such as family name (last name), a given name (first name), or an email address. This generates the customer.created event.

  5. Return to the webhook.site page to view the event notification.

After you verify that your event notification subscription is working, you need to add code to your notification URL so that your application can process the event information. Because your notification URL is public and can be called by anyone, you must validate each event notification to confirm that it came from Square. A non-Square post can potentially compromise your application. 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 signature key, the 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 event notification you received.

Important

A malicious agent can compromise your notification endpoint by using a timing analysis attack to determine the key you are 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.

The following functions generates an HMAC-SHA1 signature from your signature key, the notification URL, and the event notification body. You can then compare the result with the event notification's x-square-signature.

Web event notification authentication - Javascript Permalink Get a link to this section

// The crypto module provides cryptographic functionality
const crypto = require('crypto');
// The notification URL
const NOTIFICATION_URL = 'https://us-sampleurl.net/webhook';

// event notification subscription signature key (sigKey) defined in 
// dev portal for app
// Note: Signature key is truncated for illustration
const sigKey = 'uTYf8X...0HGvYg';

function isFromSquare(NOTIFICATION_URL, request, sigKey) {
  const hmac = crypto.createHmac('sha1', sigKey);
  hmac.update(NOTIFICATION_URL + JSON.stringify(request.body));
  const hash = hmac.digest('base64');

  return request.get('X-Square-Signature') === hash;
}

Webhook event notification authentication - Python Permalink Get a link to this section

import hmac
import base64
import json
# URL where event notifications are sent - in this example, webhook.site 
NOTIFICATION_URL = 'https://webhook.site/8f6d7efe-9b4f-4213-887b-8c8e039c93ba'
# Signature key for the webhooks endpoint
sigKey = b'9-ctc8Uq3BiIIdXWY7L4Rg'

# body of the webhook event notification - in file for testing purposes
with open('message.json') as file:
    square_request = file.read()

# remove white space from body of webhook event notification
clean_request = json.dumps(json.loads(square_request), separators=(',', ':'))

# concatenate and encode result 
url_request_bytes = NOTIFICATION_URL.encode('utf-8') + clean_request.encode('utf-8')

# create hmac
hmac_code = hmac.new(key=sigKey, msg=None, digestmod='sha1')
hmac_code.update(url_request_bytes)
hash = hmac_code.digest()

# print hash as base64
print(base64.b64encode(hash))