Webhooks in the Square Connect API

Written by Stephen Barlow.

Square’s partners have contributed an expansive collection of app integrations to our platform over the past year. From accounting solutions like Intuit Quickbooks and Xero, to the Fresh KDS kitchen display system, these integrations give merchants even more tools to help them run their business — and they are all built on top of the Square Connect API.

The Square Connect API is available to everyone. If you’re a developer (who also happens to run a business on Square), you can build applications to download your business’s transaction history and help manage your items catalog.

Recently we launched a new API feature: Webhooks. Now, your application can get real-time notifications when you process a payment or refund. Let’s try it out!

Webhooks in six steps

1. Create a Square account. If you don’t already have a free Square account for your business, download the Square Register app to your Android or iOS device and create one.

2. Set up a server to listen for notifications. Webhook notifications come in as HTTP POST requests, so you’ll need a server running to listen for them. For this example, head to requestcatcher.com and create a subdomain (such as example.requestcatcher.com). Run the sample curl command it provides to confirm that the server is listening.

3. Register an application with Square. Sign in to connect.squareup.com/appsand create a new app. After you click Save, copy the personal access tokenthat’s generated for your application. This token lets you access your own merchant data with the Connect API.

4. Enable Webhooks support. While you’re on the Apps page, scroll down to the Webhooks section and click Enable Webhooks if it isn’t already enabled. Also specify the URL that your server is listening on (e.g., http://example.requestcatcher.com/test)) and click Save again.

5. Subscribe to webhook notifications. Your application is ready to receive webhook notifications, but it still needs to specify which merchants it wants to receive notifications for. Subscribe to notifications for your own merchant account with the following curl request, substituting your personal access token where indicated:

curl -X PUT -H “Authorization: Bearer PERSONAL_ACCESS_TOKEN” -H “Content-Type: application/json” -d “[\”PAYMENT_UPDATED\”]” [https://connect.squareup.com/v1/me/webhooks](https://connect.squareup.com/v1/me/webhooks)

6. Create a payment. Open up Square Register on your Android or iOS device and simulate a cash payment. Within about thirty seconds, your requestcatcher.com page should receive a POST request with a JSON body similar to the following:

{ 
“merchant_id”: “JGHJ0343”, 
“event_type”: “PAYMENT_UPDATED”, 
“entity_id”: “Jq74mCczmFXk1tC10GB”
}

A full-fledged application could then pass the value of entity_id along to the Connect API’s Retrieve Payment endpoint to get the full details of the updated payment.

And that’s Webhooks! We’re really excited to see what developers can build with them. For more in-depth info on all things Connect API, check out the documentation. This Github sample also demonstrates a basic web server that listens for webhook notifications.

As always, if you hit a snag working with the Connect API, don’t hesitate to post a question with the square-connect label to Stack Overflow.

Happy coding! Stephen Barlow Voice actor, technical writer, co-creator of Kanye Zone & Pitbull Partymedium.com