v1 Webhooks

Subscribe to Events

Subscribe to Square Webhook events for the Connect v1 API.

Web
Webhooks API

Prerequisites and assumptions
Permalink Get a link to this section

You must have a Square account to use Square Webhooks. Create a Square account in minutes if you don't already have one.

This guide also makes the following assumptions:

  • You have read Webhooks What it Does for an overview of how Square Webhooks work.

  • You are subscribing to events on the Connect v1 API.

  • You are familiar with HTTP, cURL, and PHP.

Information you will need
Permalink Get a link to this section

To use the steps in this guide you will need the following information:

  • A valid access token. Square recommends testing with sandbox credentials whenever possible. See Square API Access Tokens for more information.

  • An active location ID. Copy a valid Developer Account location ID from the Locations setting page of your Square application in the Developer Dashboard, or set the dashboard to Sandbox Settings mode and then copy a sandbox location ID.

Step 1: Subscribe to Square Webhook v1 notifications
Permalink Get a link to this section

To initialize your webhook listener, you need to subscribe to the Connect v1 events you want notifications for. You only need to do this once. The quickest way to subscribe to webhook events is to use the following cURL command.

Important

The following subscription command cannot be used to subscribe to Connect v2 events. To subscribe to v2 events, go to the Developer Portal to add v2 event subscriptions.

Open the Mac Terminal or Windows Command Prompt. Then, enter the cURL command. In the command:

  • Replace ACCESS_TOKEN with the access token for the account being targeted.

  • Replace LOCATION_ID with a valid location ID for the account being targeted.

  • Replace EVENT_LIST with a comma-separated list of the notification events you want to subscribe to. EVENT_LIST uses the following syntax:

    ["PAYMENT_UPDATED", "INVENTORY_UPDATED"]
    

    See the list of Available webhook events in the Connect Technical Reference for possible values.

curl -X PUT                                      \
-H "Authorization: Bearer ACCESS_TOKEN"          \
-H "Content-Type: application/json"              \
-d '[EVENT_LIST]'                                \
https://connect.squareup.com/v1/LOCATION_ID/webhooks

If the subscription request is successful, you will receive an array with all the webhook notifications you are now subscribed to.

Step 2: Set up notification URL in your application dashboard
Permalink Get a link to this section

  1. Go to the Dashboard.

  2. Click on the app you want to enable webhooks for. Then, click on the Webhooks tab.

  3. Click enable Webhooks.

  4. Add a link to your notification URL

Step 3 Optional: Test your webhook events with a test webhooks listener
Permalink Get a link to this section

You can test your webhook subscriptions using webhook.site to make sure they are sending events before you finish setting up your notification URL.

  1. In a new tab, go to https://webhook.site and create a subdomain. It will automatically generate a notification URL for you to use. Copy the URL.

  2. Go to the Application Dashboard and click the application you want to work with. Select the Webhooks tab.

  3. Click Enable Webhooks if it is not already enabled.

  4. In the Notification URL field, paste the URL you received from webhook.site.

  5. Click Save.

Important

If you use webhook.site for testing, be sure to update your Notification URL settings before moving your webhook functionality to production.

Next steps

Learn about validating webhook notifications on a notification endpoint