Skip to content
HookDeploy

Square webhooks

Last verified against Square's documentation on September 27, 2026.

On this page ↓

Square sends webhooks when something happens to a payment, an order, a refund, an invoice, or a customer. Its signature covers the notification URL as well as the body, which is the detail that breaks verification behind proxies, and it matters with HookDeploy too. Square retries for up to 24 hours and then discards the event. This page covers what Square sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Square sends webhooks for

AreaExample eventsTypical use
Paymentspayment.created, payment.updatedTrack payment status
Refundsrefund.created, refund.updatedRecord refunds
Ordersorder.created, order.updated, order.fulfillment.updatedSync orders and fulfillment
Invoicesinvoice.payment_made, invoice.scheduled_charge_failedTrack invoice payments
Customerscustomer.created, customer.updatedSync customer records

Each webhook is a JSON POST with a merchant_id, a type, an event_id, a created_at timestamp, and the object under data.

How Square delivers webhooks

BehaviorDetail
Method and formatPOST with a JSON body
Signature headerx-square-hmacsha256-signature
Signing schemeBase64 HMAC-SHA256 over the subscription’s notification URL followed by the raw body, keyed with the subscription’s signature key
Metadata headerssquare-environment, square-initial-delivery-timestamp, square-retry-number, and square-retry-reason
SuccessAny 2xx
RetriesWith exponential backoff for up to 24 hours, then the event is discarded
RecoveryThe Events API lists past events
Deduplicationevent_id

Common Square webhook errors and how to fix them

Signature never matches

  • Wrong URL. The signature starts with the notification URL exactly as configured in the subscription, including scheme, trailing slash, and query string. Behind a proxy your app sees a different URL, so read it from configuration.
  • Wrong key. Use the subscription’s signature key, not an access token. Each subscription has its own key, and sandbox and production are separate.
  • Parsed body. Sign the raw bytes.
  • Legacy header. x-square-signature is the deprecated SHA1 version. Verify x-square-hmacsha256-signature.

Events lost after an outage

Square gives up after 24 hours. Recover missed events through the Events API.

Events out of order

Use created_at and the object’s version fields, and fetch the object from the API when order matters.

Duplicate events

Retries resend the same event. Deduplicate on event_id.

Why use HookDeploy with Square

Keep events past Square’s 24 hours

HookDeploy captures every Square webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down for longer than a day, the events are still in HookDeploy.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

One webhook, many systems

Send each Square event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Square can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Square events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Square events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Signatures and URLs. Square signs the HookDeploy URL you registered, so your handler must use that URL when it verifies. See below.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Square treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Signatures through HookDeploy

Square signs the notification URL you registered, which with HookDeploy is your HookDeploy endpoint URL. HookDeploy forwards the body and x-square-hmacsha256-signature unchanged, so your handler can verify the signature, as long as it signs with that registered HookDeploy URL, not its own.

If you add an endpoint token to the URL as ?token=, it’s part of the registered URL, so include it in the string you sign. HookDeploy removes the token before forwarding, so read the full registered URL from configuration rather than rebuilding it from the request.

The signature has no timestamp, so retries and replays verify like the original delivery. Deduplicate on event_id.

Set up Square with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Square production) and copy its URL.
  2. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  3. In the Square Developer Console, open your application’s Webhooks, add a subscription with your HookDeploy URL as the notification URL, and choose your events. Copy the signature key.
  4. Configure your handler with the signature key and the exact notification URL you registered.
  5. Send a test event from the subscription, and confirm it appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
// The notification URL exactly as registered in Square: your HookDeploy URL, query string included.
const NOTIFICATION_URL = process.env.SQUARE_NOTIFICATION_URL;

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/square', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.SQUARE_SIGNATURE_KEY)
    .update(NOTIFICATION_URL + req.body.toString('utf8'))   // URL first, then the raw body
    .digest('base64');
  const received = req.get('x-square-hmacsha256-signature') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid signature');

  res.sendStatus(200);
  const event = JSON.parse(req.body.toString('utf8'));
  await enqueue({ eventId: event.event_id, type: event.type, data: event.data });
  // Deduplicate on eventId in your worker.
});

FAQ

How is the Square webhook signature calculated?

Square computes an HMAC-SHA256 over the subscription's notification URL followed by the raw request body, keyed with the subscription's signature key, and sends it base64-encoded in x-square-hmacsha256-signature.

Why does Square signature verification fail behind a proxy?

The signature includes the notification URL. Behind a proxy, a load balancer, or HookDeploy, your app sees a different URL. Always sign with the URL exactly as registered in Square, from configuration.

How long does Square retry webhooks?

Square retries with exponential backoff for up to 24 hours, then discards the event. Use the Events API to recover events you missed.

Which key do I use to verify Square webhooks?

The signature key of that webhook subscription, not an access token. Each subscription, and each environment, has its own key.

How do I deduplicate Square webhooks?

Use the event_id, which stays the same across retries of the same event.

Does HookDeploy break Square signature verification?

Not if you sign with the right URL. Square signs the HookDeploy URL you registered, and HookDeploy forwards the body and signature unchanged. Your handler must use that registered URL, including any query string, when it computes the signature.

Capture Square webhooks free

Start free