An introduction to the Webhook Subscriptions API, which you can use to programmatically subscribe to webhooks.
Webhook Subscriptions API

Webhook Subscriptions API Overview Beta release
This is pre-release documentation for an API in public beta and is subject to change.

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.

    Note

    Because webhook subscriptions are owned by the application and not by any one seller, you can't use OAuth access tokens with the Webhook Subscriptions API. You must use the application's personal access token.

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.

The following is an example response:

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.

    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.

    The following is an example response:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40
    • 41
    • 42
    {
      "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.

    The following is an example response:

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

    The following is an example response:

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.

The following is an example response:

We've made improvements to our docs.
Prefer the old format?