Webhook Subscriptions API Overview

Using the Developer Dashboard to manually update webhook subscriptions can become complex when you have to update numerous applications for new event types or functionality.

The Webhook Subscriptions API lets you programmatically manage your webhook subscriptions, including creating, updating, and deleting webhook subscriptions associated with an event.

With the Webhook Subscriptions API, you can:

• Subscribe to receive notifications of events you want to know about. To subscribe, you need to register a notification URL, which Square sends notifications to when events occur.
• Retrieve all event types that an application can subscribe to.
• List all subscriptions for an application.
• Trigger a test notification to the subscription's notification URL.

With the Webhook Subscriptions API, you can integrate webhook subscriptions into CI/CD (Continuous Integration/Continuous Delivery) pipelines. For example, you can rotate the signature key used to sign webhooks, configure webhooks while bootstrapping applications and test environments, and update webhooks for new event types or API versions.

Consider a scenario where you want to rotate the signature key every 90 days. You can call UpdateWebhookSubscriptionSignatureKey to get a new key that you can use to validate all future webhooks with.

curl https://connect.squareup.com/v2/webhooks/subscriptions/wbhk_b35f6b3145074cf9ad513610786c19d5/signature-key \
  -X POST \
  -H 'Square-Version: 2022-08-17' \
  -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "ed80ae6b-0654-473b-bbab-a39aee89a60d"
  }'

The following is an example response:

{
  "signature_key": "mAskrnZb__o9fdCO42C8zg"
}

The following steps show how to configure webhooks for an application from scratch:

1. Check whether the application has existing subscriptions with the ListWebhookSubscriptions endpoint.

   curl https://connect.squareup.com/v2/webhooks/subscriptions \
     -H 'Square-Version: 2022-08-17' \
     -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \
     -H 'Content-Type: application/json'

   The following is an example response for an application with no existing subscriptions:

   {}

2. Use the ListWebhookEventTypes endpoint to see all the event types that you can subscribe to.

   curl https://connect.squareup.com/v2/webhooks/event-types \
     -H 'Square-Version: 2022-08-17' \
     -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \
     -H 'Content-Type: application/json'

   The following is an example response:

   {
     "event_types": [
       "payment.created",
       "order.updated",
       "invoice.created",
       "booking.created",
       "card.disabled",
       "customer.created"
     ],
     "metadata": [
       {
         "event_type": "payment.created",
         "api_version_introduced": "2020-02-26",
         "release_status": "PUBLIC"
       },
       {
         "event_type": "order.updated",
         "api_version_introduced": "2020-04-22",
         "release_status": "BETA"
       },
       {
         "event_type": "invoice.created",
         "api_version_introduced": "2020-07-22",
         "release_status": "PUBLIC"
       },
       {
         "event_type": "booking.created",
         "api_version_introduced": "2020-12-16",
         "release_status": "PUBLIC"
       },
       {
         "event_type": "card.disabled",
         "api_version_introduced": "2021-06-16",
         "release_status": "PUBLIC"
       },
       {
         "event_type": "customer.created",
         "api_version_introduced": "2021-02-26",
         "release_status": "PUBLIC"
       }
     ]
   }

3. Use the CreateWebhookSubscription endpoint to add your notification URL and list of events that you want to subscribe to.

   curl https://connect.squareup.com/v2/webhooks/subscriptions \
     -X POST \
     -H 'Square-Version: 2022-08-17' \
     -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "idempotency_key": "63f84c6c-2200-4c99-846c-2670a1311fbf",
       "subscription": {
         "name": "Example Webhook Subscription",
         "event_types": [
           "payment.create",
           "order.updated",
           "invoice.created"
         ],
         "notification_url": "https://example-webhook-url.com",
         "api_version": "2021-12-15"
       }
     }'

   The following is an example response:

   {
     "subscription": {
       "id": "wbhk_b35f6b3145074cf9ad513610786c19d5",
       "name": "Example Webhook Subscription",
       "enabled": true,
       "event_types": [
           "payment.created",
           "order.updated",
           "invoice.created"
       ],
       "notification_url": "https://example-webhook-url.com",
       "api_version": "2021-12-15",
       "signature_key": "1k9bIJKCeTmSQwyagtNRLg",
       "created_at": "2022-08-17 23:29:48 +0000 UTC",
       "updated_at": "2022-08-17 23:29:48 +0000 UTC"
     }
   }

4. To validate the notification URL, use the TestWebhookSubscription endpoint.

   curl    https://connect.squareup.com/v2/webhooks/subscriptions/wbhk_b35f6b3145074cf9ad513610786c19d5/test \
     -X POST \
     -H 'Square-Version: 2022-08-17' \
     -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "event_type": "payment.created"
     }'

   The following is an example response:

   {
     "subscription_test_result": {
       "id": "23eed5a9-2b12-403e-b212-7e2889aea0f6",
       "status_code": 404,
       "payload": "   {\"merchant_id\":\"1ZYMKZY1YFGBW\",\"type\":\"payment.created\",\"event_id\":\"23e  ed5a9-2b12-403e-b212-7e2889aea0f6\",\"created_at\":\"2022-01-  11T00:06:48.322945116Z\",\"data\":{\"type\":\"payment\",\"id\":\"KkAkhdMsgzn59SM8A89WgKwekxLZY\",\"object\":{\"payment\":{\"amount_money\":{\"amount\":100,\"currency\":\"USD\"},\"approved_money\":{\"amount\":100,\"currency\":\"USD\"},\"capabilities\":[\"EDIT_TIP_AMOUNT\",\"EDIT_TIP_AMOUNT_UP\",\"EDIT_TIP_AMOUNT_DOWN\"],\"card_details\":{\"avs_status\":\"AVS_ACCEPTED\",\"card\":{\"bin\":\"540988\",\"card_brand\":\"MASTERCARD\",\"card_type\":\"CREDIT\",\"exp_month\":11,\"exp_year\":2022,\"fingerprint\":\"sq-1-Tvruf3vPQxlvI6n0IcKYfBukrcv6IqWr8UyBdViWXU2yzGn5VMJvrsHMKpINMhPmVg\",\"last_4\":\"9029\",\"prepaid_type\":\"NOT_PREPAID\"},\"card_payment_timeline\":{\"authorized_at\":\"2020-11-22T21:16:51.198Z\"},\"cvv_status\":\"CVV_ACCEPTED\",\"entry_method\":\"KEYED\",\"statement_description\":\"SQ *DEFAULT TEST ACCOUNT\",\"status\":\"AUTHORIZED\"},\"created_at\":\"2020-11-22T21:16:51.086Z\",\"delay_action\":\"CANCEL\",\"delay_duration\":\"PT168H\",\"delayed_until\":\"2020-11-29T21:16:51.086Z\",\"id\":\"hYy9pRFVxpDsO1FB05SunFWUe9JZY\",\"location_id\":\"S8GWD5R9QB376\",\"order_id\":\"03O3USaPaAaFnI6kkwB1JxGgBsUZY\",\"receipt_number\":\"hYy9\",\"risk_evaluation\":{\"created_at\":\"2020-11-22T21:16:51.198Z\",\"risk_level\":\"NORMAL\"},\"source_type\":\"CARD\",\"status\":\"APPROVED\",\"total_money\":{\"amount\":100,\"currency\":\"USD\"},\"updated_at\":\"2020-11-22T21:16:51.198Z\",\"version_token\":\"FfQhQJf9r3VSQIgyWBk1oqhIwiznLwVwJbVVA0bdyEv6o\"}}}}",
       "created_at": "2022-08-17 00:06:48.322945116 +0000 UTC m=+3863.054453746",
       "updated_at": "2022-08-17 00:06:48.322945116 +0000 UTC m=+3863.054453746"
     }
   }

Webhook subscriptions are versioned independent of the default version of your application. The version of a webhook subscription determines the version of the event that's sent to the webhook.

Imagine you want the new event types or data object fields added in subsequent releases to show up in your webhooks. You can use the UpdateWebhookSubscription endpoint to change the api_version field to the newer version and add the newer event_types that you want to get notified for. You can also edit the subscription name or notification_url, as well as enable or disable the subscription.

curl https://connect.squareup.com/v2/webhooks/subscriptions/wbhk_b35f6b3145074cf9ad513610786c19d5 \
  -X PUT \
  -H 'Square-Version: 2022-08-17' \
  -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscription": {
      "api_version": "2022-08-17",       
      "enabled": true,
      "event_types": [
        "payment.created",
        "order.updated",
        "invoice.created",
        "customer.deleted"
      ],
      "name": "Updated Example Webhook Subscription"
    }
  }'

The following is an example response:

{
  "subscription": {
    "id": "wbhk_b35f6b3145074cf9ad513610786c19d5",
    "name": "Updated Example Webhook Subscription",
    "enabled": true,
    "event_types": [
      "payment.created",
      "order.updated",
      "invoice.created",
      "customer.deleted"
    ],
    "notification_url": "https://example-webhook-url.com",
    "api_version": "2022-08-17",
    "created_at": "2022-08-17 23:29:48 +0000 UTC",
    "updated_at": "2022-08-17 23:45:51 +0000 UTC"
  }
}