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.

Link to section
Example use cases

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.

Link to section
Rotating the signature key

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"
}

Link to section
Configure webhooks for an application from scratch

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

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:

{}

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:

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"
    }
  ]
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "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"
  }
}

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"
  }
}

Link to section
Update a webhook subscription

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "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"
  }
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

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

Note

Link to section Example use cases

Link to section Rotating the signature key

Link to section Configure webhooks for an application from scratch

Link to section Update a webhook subscription

Webhook Subscriptions API Overview Beta release

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

Link to section
Example use cases

Link to section
Rotating the signature key

Link to section
Configure webhooks for an application from scratch

Link to section
Update a webhook subscription