Test Square Webhooks Locally

From a stuck handler to a live Square delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 8000. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL, something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3Open the Developer Console (developer.squareup.com/apps), choose Open on your application, and set the Sandbox / Production toggle at the top of the page. In the left pane, under Webhooks, choose Subscriptions → Add subscription. Enter a name and your LocalCan URL with your route, e.g. https://your-app-12.localcan.dev/square/webhook, pick an API version that covers the events you want, select them, and choose Save. Then reopen the subscription and choose Show in the Signature Key box on Endpoint Details.
4. 4On the Webhook subscriptions page for your application (developer.squareup.com/apps), choose your subscription, and in the Endpoint details pane choose More → Send test event. Pick an event and choose Send: the window reports the response code and the body it delivered. For real events, drive the Sandbox from API Explorer. A CreatePayment call fires the matching notification.
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body. Expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

Square saysYour webhook for webhook was not created. URL is not valid

Header

x-square-hmacsha256-signature

Algorithm

HMAC-SHA-256, base64-encoded

What's signed

Square signs the notification URL immediately followed by the raw request body. No separator, nothing time-based anywhere in the input. The key is your subscription’s signature key as plain UTF-8 bytes, no prefix to strip and no base64 to decode, and the digest is base64. The URL must be byte-identical to the one saved on the subscription, so a http for https or an added trailing slash breaks the compare while the request looks perfect. Square names the three inputs but leaves the order to the SDK helper: this concatenation is what WebhooksHelper.verifySignature computes.

Secret

The signature key from Developer Console → your application → Webhooks → Subscriptions → your subscription → Endpoint Details, where you choose Show in the Signature Key box (developer.squareup.com/apps). No prefix, one key per subscription, and Sandbox and Production hold entirely different ones behind the environment toggle.

import express from 'express'
import crypto from 'crypto'

// If you already have the SDK, this is the one-liner Square documents:
//   await WebhooksHelper.verifySignature({ requestBody, signatureHeader,
//     signatureKey, notificationUrl })
// The code below is the same computation spelled out, because Square documents
// the helper rather than the string it hashes.

// Must match the subscription's notification URL byte for byte. It is hashed.
const NOTIFICATION_URL = 'https://your-app-12.localcan.dev/square/webhook'
const SIGNATURE_KEY = process.env.SQUARE_WEBHOOK_SIGNATURE_KEY

function isFromSquare(rawBody, signatureHeader) {
  if (!signatureHeader) return false

  // notification URL + raw body, concatenated with no separator. No timestamp.
  // The signature key is the HMAC key as-is: no prefix strip, no base64 decode.
  const payload = NOTIFICATION_URL + rawBody
  const expected = crypto
    .createHmac('sha256', SIGNATURE_KEY)
    .update(payload, 'utf8')
    .digest('base64')

  // Square's docs ask for a constant-time compare here; its own SDK uses ===.
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

const app = express()

// Raw bytes only. express.json() parses and re-serializes, which changes the
// string being hashed. The classic case is a description field with newlines.
app.post('/square/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const rawBody = req.body.toString('utf8')
  const signature = req.headers['x-square-hmacsha256-signature']

  if (!isFromSquare(rawBody, signature)) {
    return res.status(403).end()  // discard: it did not come from Square
  }

  const event = JSON.parse(rawBody)

  // Acknowledge inside the 10-second budget, then do slow work off the request.
  // event.event_id is the idempotency value: key your writes on it.
  res.status(200).end()
  // ... then handle event.type / event.data.object off the request path
})

A replayed capture verifies indefinitely. Square signs no timestamp and documents no tolerance window (square-initial-delivery-timestamp is a header, not an HMAC input), so a delivery captured last week still passes today, the opposite of Stripe or Svix. Two things do invalidate it: rotating the subscription’s signature key, and changing the notification URL, since the old digest was computed over the old string.