How to validate webhook from Square — Complete Developer Guide

What does "validate webhook from Square" mean?

When Square fires a payment event, its webhook body contains dozens of nested fields specific to its internal data model. To validate webhook means extracting only the relevant data and converting it to a flat, universally consumable format — without any custom parsing logic on your end.

The normalized output always follows the same 6-field schema regardless of the source platform:

{
  "platform":       "square",
  "transaction_id": "pi_3ABC...",
  "amount":         49.99,
  "currency":       "USD",
  "customer_email": "buyer@example.com",
  "payment_status": "succeeded"
}

Raw Square webhook example

This is the actual payload Square POSTs to your server endpoint:

{
  "merchant_id": "MERCHANT123",
  "type": "payment.completed",
  "data": {
    "object": {
      "payment": {
        "id": "abc123",
        "amount_money": { "amount": 4999, "currency": "USD" },
        "buyer_email_address": "buyer@example.com"
      }
    }
  }
}

As you can see, the object contains dozens of fields irrelevant to most integration use cases. The Webhook Translator API strips the noise and returns only the essential contract.

How to validate webhook from Square in under 60 seconds

Option 1 — API call (recommended)

Forward the raw webhook with a single query parameter:

POST https://webhook-translator-microapi.vercel.app/?plataforma=square
Content-Type: application/json
X-RapidAPI-Key: YOUR_KEY

[Square webhook body here]

Option 2 — Manual Node.js parser

// ⚠ You must maintain this code on every Square API update
const amount = event.data.object.amount_received / 100;
const email = event.data.object.customer_email
           ?? event.data.object.billing_details?.email;
// ... 20+ more lines to handle all edge cases and platform versions

Related documentation