Square Webhooks

When to Use This Skill

• How do I receive Square webhooks?
• How do I verify Square webhook signatures?
• How do I handle payment.updated or refund.created events?
• Why is my Square webhook signature verification failing?
• Setting up Square webhook handlers for payments, refunds, invoices, or orders

Verification (core)

Square signs each webhook with an HMAC-SHA256 over the notification URL concatenated with the raw request body (notificationUrl + rawBody, in that order — confirmed by testing), base64-encoded, delivered in the x-square-hmacsha256-signature header. The notification URL is part of the signed content, so it must exactly match — byte-for-byte — the URL configured in your Square subscription. Always verify the raw body — never JSON.parse first.