How to Receive Square Webhooks Reliably

Square can notify your systems about payments, orders and refunds through webhooks. Square POSTs the event to your URL and signs it — but you still have to verify that signature (Square signs the notification URL plus the body, which trips people up), retry on failure, and reshape the payload for whatever consumes it. Bluejay Relay does all of that without a backend.

What You'll Build

Square → Bluejay Relay (verify + transform + route) → your app, accounting tool, or Slack.

1. Create the Webhook Endpoint

In Bluejay Relay, create a webhook, pick Square as the source, and copy your capture URL:

https://in.bluejayrelay.com/api/webhooks/{your-token}

2. Subscribe in the Square Dashboard

In the Square Developer Dashboard, open your application's Webhooks, add a subscription, set the notification URL to your Bluejay capture URL, and choose events (for example payment.created, order.updated). Square shows a signature key — copy it.

3. Verify the Signature

This is the step people get wrong: Square's signature is an HMAC-SHA256 of the notification URL concatenated with the raw body, base64-encoded, in the x-square-hmacsha256-signature header — not the body alone. Bluejay Relay knows the exact URL Square hit and verifies it correctly; paste your signature key and enable verification. Anything that doesn't match is rejected.

4. Transform and Route

Square payloads are deeply nested (data.object.payment...). Relay's field mapping flattens the fields you need — amount, status, order id — into a clean payload for your API, your accounting system, or a Slack alert. Fan out to several at once.

5. Retries and Replay

Destination down? Relay retries with backoff, dead-letters persistent failures, and lets you replay — individually or in bulk — so you never drop a payment event.

---

Receive Square webhooks free on Bluejay Relay — 10,000 events/month, no card required.