v1 Webhooks

How It Works

A deeper look at the Webhooks API for Connect v1 events

Backend
Webhooks API

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

Consider an application that uses webhooks to send manufacturing requests when customers place orders through a merchant webstore.

Before an application can use webhooks, the following needs to happen:

  • The application backend needs to initialize the webhook listener by subscribing to payment updates.

  • The application needs to have a notification URL and that URL needs to be set in the Application Control Panel.

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, which triggers the PAYMENT_UPDATED notification.

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

  5. The webhooks listener receives a JSON message with information on the completed transaction (which includes the transaction ID) and validates the authenticity of the notification.

  6. The webhooks listener uses the transaction information to call Square APIs for more information and then constructs an email message and sends it to manufacturing.

Here is an example of the request body:

{
  "merchant_id": "18YC4JBH91E1H",
  "location_id": "JGHJ0343",
  "event_type": "PAYMENT_UPDATED",
  "entity_id": "Jq74mCczmFXk1tC10GB"
}

Note

For Connect API applications created after February 16, 2016, use location_id and entity_id to identify and retrieve transactions associated with a webhook event. Connect API applications created before February 16, 2016 are single location merchants. Transactions created by these applications are accessed using merchant_id and entity_id.

Events
Permalink Get a link to this section

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

  • PAYMENT_UPDATED — Triggered when a charge is made or refunded through Point of Sale or through API calls to Connect v2 Transaction endpoints.

  • INVENTORY_UPDATED — Triggered when the inventory quantity for a catalog item is updated.

  • TIMECARD_UPDATED — Triggered when an employee clocks in using the Point of Sale app or when a timecard is created in the merchant dashboard.

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.

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.

Important

The Webhooks API is not included in the Connect SDK suites. Webhooks functionality is only accessible through REST endpoints.