Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
v2 Webhooks

How It Works

A deeper look at v2 Webhooks for Square events

Backend
Webhooks API

The v2 Webhooks process flow
Permalink Get a link to this section

Consider an application that uses webhooks to update offline inventory reports when customers purchase items through a merchant webstore.

Before an application can use webhooks, the application backend developer needs to do the following:

  • Use the Developer Portal to configure a client subscription with a notification URL and selected webhook event types.

  • Initialize an application webhook listener at the notification URL.

An example webhook notification
Permalink Get a link to this section

Here is an example of how the application responds to webhook notifications as customers complete the purchase flow on the merchant webstore:

  1. A customer provides payment information.

  2. The application backend packages and sends a transaction request.

  3. Square processes the transaction.

  4. The application backend packages and sends an inventory adjustment request.

  5. Square processes the adjustment request, which triggers the inventory.count.updated notification.

  6. Square Webhooks sends a notification to the listener URL configured in the application control panel.

  7. The webhooks listener receives a JSON message with information on the inventory item adjustment (which includes the catalog object ID) and validates the authenticity of the notification.

  8. The webhooks listener uses the adjustment information to call Square APIs for information about the related catalog item and then updates the offline inventory report with catalog and inventory quantity information.

Request body example
Permalink Get a link to this section

This webhook notification shows actionable information about a batch of up to 100 individual inventory count updates.

{
  "merchant_id": "6SSW...5",
  "type": "inventory.count.updated",
  "event_id": "df5f3813-a913-45a1-94e9-fdc3f7d5e3b6",
  "created_at": "2019-10-29T18:38:45.455006797Z",
  "data": {
    "type": "inventory",
    "id": "84e4ac73-d605-4dbd-a9e5-ffff794ddb9d",
    "object": {
      "inventory_counts": [
        {
          "calculated_at": "2019-10-29T18:38:45.10296Z",
          "catalog_object_id": "FGQ5JJWT2PYTHF35CKZ2DSKP",
          "catalog_object_type": "ITEM_VARIATION",
          "location_id": "YYQR03DGCTXA4",
          "quantity": "10",
          "state": "IN_STOCK"
        }
      ]
    }
  }
}

Events
Permalink Get a link to this section

Square Webhooks sends notifications to an application when triggered by the following events:

  • inventory.count.updated — Triggered when the inventory quantity for a catalog item is updated. Read about Inventory Webhooks to learn how to process an inventory count notification.

  • catalog.version.updated — Triggered when a catalog is updated. Read about Catalog Webhooks to learn how to process a catalog notification.

  • labor.shift.created — Triggered when a worker starts a shift. Read about Labor Webhooks to learn how to process a shift created notification.

  • labor.shift.updated — Triggered when a Shift is updated. Read about Labor Webhooks to learn how to process a Shift update.

  • labor.shift.deleted — Triggered when a Shift is deleted. Read about Labor Webhooks to learn how to process the deletion of a Shift.

When a trigger event occurs, Square Webhooks collects data on the event, creates a notification, and sends it as a POST request to the notification URL configured in the Square Dashboard.

Event metadata headers
Permalink Get a link to this section

Notifications for these events also include the following metadata headers:

  • Square-Initial-Delivery-Timestamp — Delivery time of the initial notification delivery as an RFC 339 timestamp.

  • Square-Retry-Number — The number of times Square has resent a notification for the given event (including the current retry) as an integer. The retry number does not include the original notification and is only present when there has been at least one unsuccessful delivery.

  • Square-Retry-Reason — The reason why the last notification delivery failed. The retry reason is only present when there is at least one unsuccessful delivery and has the following possible values:

    • http_timeout — the client server took longer than 10 seconds to respond.

    • http_error — the client server responded with a non-2xx status code.

    • ssl_error — Square could not verify the client SSL certificate.

    • other_error — something unexpected occurred.

  • X-Square-Signature — An HMAC-SHA1 signature used to validate the event authenticity.

  • Square-Environment — The Square account environment that generated the webhook event. Can be one of Production,Sandbox.

Did you know?

If you have declared a application webhook listener to process webhook notifications from both production and sandbox environments, you should detect the notification origin environment and process the notification appropriately.

Read the Square-Environment HTTP header on the notification POST. If the notification is generated in the sandbox environment, the value is Sandbox. A production environment notification has the value Production.

if (req.header('Square-Environment') === 'Production') {
    console.log('Production webhook notification received');
} else if (req.header('Square-Environment') === 'Sandbox') {
    console.log('Sandbox webhook notification received');
}