How to Test Square Webhooks

{
  "merchant_id": "ML4F4M3A6H4G2",
  "type": "payment.updated",
  "event_id": "v1-payment-3b6e8d6f",
  "created_at": "2026-03-20T10:05:00Z",
  "data": {
    "object": {
      "payment": {
        "id": "R2B3Z4Y5X6",
        "amount_money": {
          "amount": 4200,
          "currency": "USD"
        },
        "status": "COMPLETED"
      }
    }
  }
}

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

const app = express();

app.post(
  '/webhooks/square',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-square-hmacsha256-signature'] as string | undefined;
    if (!signature) return res.status(401).send('missing signature');

    // Reconstruct the public URL Square called (be careful behind proxies).
    const notificationUrl = `https://${req.headers.host}${req.originalUrl}`;
    const stringToSign = notificationUrl + req.body.toString('utf8');

    const expected = crypto
      .createHmac('sha256', process.env.SQUARE_WEBHOOK_SIGNATURE_KEY!)
      .update(stringToSign)
      .digest('base64'); // base64, not hex

    if (
      signature.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
    ) {
      return res.status(403).send('invalid signature');
    }

    res.json({ ok: true });
  },
);

import hmac, hashlib, base64, os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.post("/webhooks/square")
async def square_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get('x-square-hmacsha256-signature', '')
    notification_url = str(request.url)  # public-facing URL Square called
    string_to_sign = notification_url.encode() + body
    expected = base64.b64encode(
        hmac.new(
            os.environ['SQUARE_WEBHOOK_SIGNATURE_KEY'].encode(),
            msg=string_to_sign,
            digestmod=hashlib.sha256,
        ).digest()
    ).decode()
    if not hmac.compare_digest(signature, expected):
        raise HTTPException(status_code=403, detail='invalid signature')
    return {'ok': True}