Webhooks API

How it Works

Details of the Square Webhooks data model.

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.

The Square Webhooks API process flow

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 response body:

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

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