Square Webhooks: Send Payment and Order Events to Sazabi

Webhook facts checked on the platform’s docs on Nov 8, 2026.

Square webhooks report payments, orders, refunds, inventory changes and more as they happen in the Dashboard, a point of sale or an API call. A Sazabi intake URL turns each notification into a searchable log record.

What Square sends

A Square webhook is a subscription that registers a notification URL, a list of event types and an API version. When a subscribed event occurs, Square POSTs the details as JSON to that URL. Events can come from the Square Dashboard, a point of sale app, other Square products and third-party apps that call Square APIs.

The event type reference includes names such as payment.created, payment.updated, order.created, order.updated, refund.created, invoice.payment_made, inventory.count.updated, dispute.created and customer.created. The API version you choose on the subscription decides which events are available.

The body has a common structure: merchant_id, an optional location_id, type, event_id, created_at and a data object. Inside data, type names the affected object, id is its ID and object holds the object as of the event.

Why send Square webhooks to Sazabi

Point of sale data arrives from places you do not control: a card reader, a staff member refunding a sale, an app from another developer. The webhook stream is a good record of what the merchant account saw.

Sazabi's Webhook Events source stores each JSON payload as a log record with the payload under webhook.* attributes. Search an event_id and you can tell whether a notification reached you once or twice. Append /square to the intake URL and Sazabi stores that as webhook.path.

Square keeps its own webhook event logs for a rolling 28 days. Records in Sazabi let you look back past that window.

Add a subscription in the Developer Console

Copy your intake URL from the Webhook Events source and keep it private. Then:

1. Open the Developer Console and choose Open for your application.
2. Under Webhooks, choose Subscriptions, then Add subscription.
3. Enter a name and the notification URL, which is your intake URL.
4. Choose an API version that includes your events, pick the events and choose Save.

The notification URL must be correctly formatted, use HTTPS and be reachable. Otherwise the console shows an error and does not create the webhook. You can also register subscriptions with the Webhook Subscriptions API. The console toggles between Sandbox and Production, so check your setup again when you move to production.

For testing, trigger an action in the Sandbox, such as creating a customer or a payment, and look for the record in Sazabi. The Developer Console's webhook logs list each notification, the status code Square received and the retry reason.

Example Square payload

This example follows the customer.created body in the Square docs. The IDs are placeholders from the docs.

{
  "merchant_id": "<merchant id>",
  "type": "customer.created",
  "event_id": "edce24d3-bf56-46b4-b5ea-40266mnaa5a84",
  "created_at": "2021-05-17T22:46:29Z",
  "data": {
    "type": "customer",
    "id": "<customer id>",
    "object": {
      "customer": {
        "given_name": "MyFirst",
        "family_name": "Customer",
        "creation_source": "THIRD_PARTY",
        "version": 0
      }
    }
  }
}

Square also sends headers. square-environment is Production or Sandbox, and square-retry-number and square-retry-reason appear once a delivery has failed. Those are HTTP headers, outside the JSON body.

What to watch for

• Acknowledge fast. Respond with a 2xx as soon as possible. Square waits 10 seconds, then sends a duplicate.
• Retry schedule. Eleven retries follow a failure, starting 1 minute after the original and ending at 24 hours. The gaps are 1, 2, 4, 8, 16, 32 and 60 minutes, then 2, 4, 8 and 8 hours.
• No ordering guarantee. Square says event order is not guaranteed, so use created_at when sequence matters.
• Disabling. If there is no 2xx response for three weeks, Square sends a warning each week and then disables the subscription.
• Gaps. Square says the Events API can recover and reconcile missed notifications. Compare record counts by day.
• Signing. Square signs each notification using the signature key, the notification URL and the body.

Related guides: PayPal and BigCommerce. Browse the integrations list or review pricing.