Use Customer Webhooks

Applies to: Customers API | Payments API | Cards API | Gift Cards API | Customer Custom Attributes API

Learn how to configure webhooks to get notified of events when a customer profile is created, updated, deleted, or merged.

Overview

Use webhooks to receive notifications when customer profiles are created, updated, or deleted. Webhooks help streamline the process of synchronizing customer data across Square and third-party applications. Webhooks also enable custom integration scenarios that respond to changes in near real time. For example, when a customer signs up for a new account, Square creates a customer profile, which triggers an event notification. After your application receives the notification, it can perform some action in response to the event, such as sending a coupon to the new customer to use for their next purchase.

Link to section

Requirements and limitations

The following requirements and limitations apply to webhooks for customer events:

Applications that use OAuth must have CUSTOMERS_READ permission to receive notifications about customer events.
You must protect personally identifiable information (PII) and other sensitive customer information that you receive in the notification. This includes information such as customer name, address, and phone number. Unless manually added in a note or other field, credit card information is never included in notification data. For more information, see Best Practices for Collecting Information.
The following operations don't invoke customer event notifications:
- Changing membership in customer segments.
- Creating or deleting customer cards. However, you can subscribe to receive notifications for Cards API events and Gift Cards API events.
- Creating, updating, or deleting a customer-related custom attribute. However, you can subscribe to receive notifications for Customer Custom Attributes API events.
- Changing customer-related integrations from other Square APIs, such as the Payments API, Orders API, Loyalty API, or Subscriptions API. For example, changing the customer ID on an order doesn't invoke a customer.updated notification.
Square doesn't send notifications for events that fail.

For general webhook requirements and limitations, components, and processes see Square Webhooks. For information about viewing webhook logs, see Webhook Event Logs.

Link to section

How customer event notifications work

Webhooks make it possible for Square to notify you when customer events occur, so you don't need to rely only on polling for changes. If you regularly poll the Customers API to synchronize stored customer data, you can use webhooks and increase the time between your polling.

A webhook is a subscription that registers your notification URL and the events that you want to be notified about. You can configure webhooks for the following customer events.

Event	Permission	Description
customer.created	`CUSTOMERS_READ`	A customer profile is created, including when customer profiles are merged into a new customer profile.
customer.deleted	`CUSTOMERS_READ`	A customer profile is deleted, including when customer profiles are merged into a new customer profile.
customer.updated	`CUSTOMERS_READ`	An attribute on a customer profile is changed, except for the following: `cards` (deprecated) `segment_ids`

When an event occurs, Square collects data about the event, creates a notification, and sends the notification as a POST request to the URL of all webhooks that are subscribed to the event.

The following actions can invoke customer events:

Using the Customer Directory in the Square Dashboard or Point of Sale application to create, delete, update, or merge customer profiles.
Calling one of the following Customers API endpoints from a third-party application:
Note that each create, update, or delete event triggers a separate webhook notification, even for bulk operations.
Integrations with other Square APIs, for example:
- CreateLoyaltyAccount in the Loyalty API creates a customer profile if a customer ID isn't provided and a matching profile cannot be found. For more information, see Integration with the Customers API.
- CreatePayment in the Payments API might create an instant profile if a customer ID isn't provided and a matching profile cannot be found.
Square performs an internal action that invokes a customer.updated event.

Link to section

Customer profile merge events

The use of different tools or information silos might produce multiple customer profiles for the same customer. For example, if a customer makes a payment without signing in to their account, Square might generate an instant profile. To maintain accurate records, Square uses automated detection to identify and merge duplicate customer profiles. In addition, sellers can merge duplicate profiles from the Customer Directory in the Square Dashboard or Square Point of Sale. For more information, see Duplicates.

In a merge operation, Square creates a new profile using aggregated properties from the existing profiles and then deletes the existing profiles. As a result, a merge operation triggers one customer.created event and at least two customer.deleted events. For more information, see Notifications for customer profile merge events.

Link to section

Subscribe to customer events

To subscribe for notifications about customer events, you can configure webhooks for your Square application. A webhook registers the URL that Square should send notifications to, the events you want to be notified about, and the Square API version.

Link to section

To configure a webhook

In the Developer Console, open your application.
In the left pane, under Webhooks, choose Subscriptions.
At the top of the page, choose Sandbox or Production. Square recommends using the Sandbox environment for testing.
Choose Add subscription, and then configure the subscription:
1. For Webhook name, enter a name such as Customers Webhook.
2. For URL, enter your notification URL. If you don't have a working URL yet, enter https://example.com as a placeholder.
3. Optional. For API version, select a Square API version. By default, this is set to the same version as the application. Customer webhooks are available starting in version 2021-02-26.
4. For Events, select customer.created, customer.deleted, and customer.updated. If you want to receive notifications about other events at the same URL, select them or configure another endpoint.
5. Choose Save.

Link to section

To validate your webhook subscription

You can send a generic notification from the Developer Console to validate that your webhook is configured correctly.

On the Webhook subscriptions page for your application, choose the webhook that you want to test.
In the Endpoint details pane, choose More, and then choose Send test event.
Select an event, and then choose Send. If the endpoint is configured correctly, the Send test event window displays the response code and notification body. You can choose View logs to open the Webhook logs page.

Did you know?

The Webhook logs page in the Square Dashboard displays webhook event notifications in real time. After you subscribe to customer.created, customer.deleted, and customer.updated events, you can use API Explorer to create, update, and delete customer profiles and then view the event logs.

Link to section

Handle customer event notifications

When customer profiles in your account are created, updated, deleted, or merged, Square sends a notification for any webhooks that are subscribed to the corresponding event.

To handle notifications, applications typically perform the following steps:

Validate the authenticity of the notification.
Respond with an HTTP 2xx response code after receiving the notification.
Inspect, process, store, or forward the notification.
Synchronize customer data or take some other action based on the event.

For code examples that show how to validate that notifications are from Square and send a 200 response code, see Verify and Validate an Event Notification.

The body of the notification is a JSON object that contains the following properties.

Property	Description
`merchant_id`	The ID of the seller whose directory contains the affected customer.
`type`	The type of event: `customer.created` `customer.deleted` `customer.updated`
`event_id`	The unique ID of this event, used for idempotency support.
`created_at`	A timestamp of when the event occurred. For example, `2021-07-30T21:59:15.286Z`
`data`	Information about the affected customer, represented by one of the following objects, depending on the event type: CustomerCreatedSquareEventData CustomerDeletedSquareEventData CustomerUpdatedSquareEventData The `data.object` property represents the `Customer` resource and includes attributes defined for the customer, except `cards` (deprecated) and `segment_ids`. If your use case requires the full `Customer` resource, use the customer ID from the notification to call the RetrieveCustomer endpoint.

Link to section

Notifications for customer.created events

A customer.created event is invoked when a customer profile is created. The following is an example event notification:

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.created",
  "event_id": "226ea61b-476d-4487-84c8-f68b142976f8",
  "created_at": "2021-01-21T19:00:04Z",
  "data": {
    "type": "customer",
    "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
    "object": {
      "customer": {
        "created_at": "2021-01-21T19:00:04.693Z",
        "creation_source": "THIRD_PARTY",
        "email_address": "[email protected]",
        "family_name": "Doe",
        "given_name": "Jane",
        "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
        "phone_number": "+12065551212",
        "preferences": {
          "email_unsubscribed": false
        },
        "updated_at": "2021-01-21T19:00:04Z",
        "version": 0
      }
    }
  }
}

Note

The following fields are removed from the returned customer object in customer.created notifications: cards (deprecated) and segment_ids.

Notifications for customer.created events from merge operations also include an event-context object. For more information, see Notifications for customer profile merge events.

Link to section

Notifications for customer.deleted events

A customer.deleted event is invoked when a customer profile is deleted. The following is an example event notification. Notifications for delete events contain "deleted": true.

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.deleted",
  "event_id": "3af6a667-34cf-42ca-bd76-96b637d8e67f",
  "created_at": "2021-01-21T19:46:09Z",
  "data": {
    "type": "customer",
    "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
    "deleted": true,
    "object": {
      "customer": {
        "creation_source": "THIRD_PARTY",
        "email_address": "[email protected]",
        "family_name": "Doe",
        "given_name": "Jane",
        "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
        "phone_number": "+12065551212",
        "preferences": {
          "email_unsubscribed": false
        },
        "version": 11
      }
    }
  }
}

Note

The following fields are removed from the customer object in customer.deleted notifications: cards (deprecated), group_ids, and segment_ids.

Notifications for customer.deleted events from merge operations also include an event-context object. For more information, see Notifications for customer profile merge events.

Link to section

Notifications for customer.updated events

A customer.updated event is invoked when a customer profile is updated, except when changes are made to the following attributes:

cards (deprecated)
segment_ids

The following is an example event notification:

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.updated",
  "event_id": "8478cc17-a7b9-40e6-b5fa-692e58794ff5",
  "created_at": "2021-01-21T19:42:51Z",
  "data": {
    "type": "customer",
    "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
    "object": {
      "customer": {
        "created_at": "2021-01-21T19:00:04.693Z",
        "creation_source": "THIRD_PARTY",
        "email_address": "[email protected]",
        "family_name": "Doe",
        "given_name": "Jane",
        "group_ids": [
          "3MEP3VM842KQZXQ9WSBJRTX73H"
        ],
        "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
        "phone_number": "+12065551212",
        "preferences": {
          "email_unsubscribed": false
        },
        "updated_at": "2021-02-10T13:02:15Z",
        "version": 3
      }
    }
  }
}

Note

The following fields are removed from the customer object in customer.updated notifications: cards (deprecated) and segment_ids.

To discover which customer profile attributes changed, compare the updated customer resource in the notification with your local copy of the customer profile.

If customer.updated events for the same customer profile occur concurrently, Square compares their version numbers and sends a webhook notification for the latest version only. If you receive multiple customer.updated notifications for the same customer profile before you process them, you can use the version field of the customer object to determine the latest version.

Link to section

Notifications for customer profile merge events

When two or more customer profiles are merged, Square creates a new customer profile using aggregated properties from the existing profiles and then deletes the existing profiles. As a result, a merge triggers a combination of notifications:

One customer.created event for the new customer profile.
Two or more customer.deleted events, one for each existing customer profile that was merged and deleted.

All notifications from a merge include an event_context field with a merge object that contains the IDs of the affected customer profiles.

"event_context": {
  "merge": {
    "from_customer_ids": [
      // ID of existing customer profile A that was merged and deleted,
      // ID of existing customer profile B that was merged and deleted,
      // ...
    ],
    "to_customer_id": // ID of new customer profile C with aggregated properties
  }
}

All notifications sent for a particular merge operation contain the same merge object.

Did you know?

If you only want to track the IDs of customer profiles affected by a merge, you can listen for customer.created events and check whether the notifications contain the event_context.merge field. This method is more efficient than checking customer.deleted events because a merge always create a single customer profile and the associated merge object contains the IDs of all affected customer profiles.

If you need additional information about the deleted customer profiles, make sure to also subscribe for customer.deleted event notifications, which include the customer object. You cannot retrieve a customer profile after it is deleted.

Link to section

Example notifications from a merge operation

In this example scenario, two customer profiles are merged, so Square sends three notifications: one customer.created notification and two customer.deleted notifications.

The customer.created notification is sent when the new profile is created. Note the following customer profile attributes:

creation_source is set to MERGE.
note lists the merge date and any non-transferable attributes.

The following is an example customer.created notification:

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.created",
  "event_id": "04d6e69f-d3dc-4fb7-a891-beb0cf7e8457",
  "created_at": "2021-01-21T23:10:38Z",
  "data": {
    "type": "customer",
    "id": "A9641GZW2H7Z56YYSD41Q12HDW",
    "object": {
      "customer": {
        "address": {
          "address_line_1": "123 Main Street",
          "administrative_district_level_1": "WA",
          "country": "US",
          "locality": "Seattle",
          "postal_code": "98104"
        },
        "birthday": "1998-09-01",
        "company_name": "ACME Inc",
        "created_at": "2021-01-21T22:59:16.271Z",
        "creation_source": "MERGE",
        "email_address": "[email protected]",
        "family_name": "Doe",
        "given_name": "John",
        "group_ids": [
          "3MEP3VM842KQZXQ9WSBJRTX73H"
        ],
        "id": "A9641GZW2H7Z56YYSD41Q12HDW",
        "note": "Favorite: Double-shot Iced Americano\n// Merged on 2021/01/21. Following fields were not transferred to the current customer:\nPhone Number: +14065551212",
        "phone_number": "+14065551112",
        "preferences": {
          "email_unsubscribed": false
        },
        "updated_at": "2021-01-21T23:10:39Z",
        "version": 0
      },
      "event_context": {
        "merge": {
          "from_customer_ids": [
            "20R574N4D0VP74N56QTRSKDJ9C",
            "P3ZRDK895X1JQCX9D3C4KEF4YG"
          ],
          "to_customer_id": "A9641GZW2H7Z56YYSD41Q12HDW"
        }
      }
    }
  }
}

Two customer.deleted notifications are sent when the two existing profiles are merged and then are automatically deleted as part of the merge operation. The following are example event notifications:

Example for existing customer profile 1:

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.deleted",
  "event_id": "1cad466e-400a-40a8-84a6-6b8c278acc95",
  "created_at": "2021-01-21T23:10:38Z",
  "data": {
    "type": "customer",
    "id": "P3ZRDK895X1JQCX9D3C4KEF4YG",
    "deleted": true,
    "object": {
      "customer": {
        "address": {
          "address_line_1": "123 Main Street",
          "administrative_district_level_1": "WA",
          "country": "US",
          "locality": "Seattle",
          "postal_code": "98104"
        },
        "birthday": "1998-09-01",
        "company_name": "ACME Inc",
        "creation_source": "DIRECTORY",
        "email_address": "[email protected]",
        "family_name": "Doe",
        "given_name": "John",
        "id": "P3ZRDK895X1JQCX9D3C4KEF4YG",
        "note": "Favorite: Double-shot Iced Americano",
        "phone_number": "+14065551112",
        "preferences": {
          "email_unsubscribed": false
        },
        "version": 10
      },
      "event_context": {
        "merge": {
          "from_customer_ids": [
            "20R574N4D0VP74N56QTRSKDJ9C",
            "P3ZRDK895X1JQCX9D3C4KEF4YG"
          ],
          "to_customer_id": "A9641GZW2H7Z56YYSD41Q12HDW"
        }
      }
    }
  }
}

Example for existing customer profile 2:

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.deleted",
  "event_id": "ca6a30a6-3c58-49ec-b626-5ed733e861ad",
  "created_at": "2021-01-21T23:10:38Z",
  "data": {
    "type": "customer",
    "id": "20R574N4D0VP74N56QTRSKDJ9C",
    "deleted": true,
    "object": {
      "customer": {
        "creation_source": "LOYALTY",
        "id": "20R574N4D0VP74N56QTRSKDJ9C",
        "phone_number": "+14065551212",
        "preferences": {
          "email_unsubscribed": false
        },
        "version": 4
      },
      "event_context": {
        "merge": {
          "from_customer_ids": [
            "20R574N4D0VP74N56QTRSKDJ9C",
            "P3ZRDK895X1JQCX9D3C4KEF4YG"
          ],
          "to_customer_id": "A9641GZW2H7Z56YYSD41Q12HDW"
        }
      }
    }
  }
}

Link to section

Test your webhooks

To test your webhook with actual resources, you can make changes to the customer profiles in your account. Make sure to test with the same environment (Sandbox or Production) that you registered for the webhook.

The following are some ways you can trigger customer event notifications.

Test from the Square Dashboard

Open the Square Dashboard.
- To test with Sandbox resources, open the the Sandbox test accounts page in the Developer Console, and then choose Square Dashboard next to the test account. This opens the Sandbox Square Dashboard associated with the test account.
- To test with production resources, open the Square Dashboard.
In the left pane, choose Marketing & loyalty and Customer directory, and then create, update, delete, or merge customers.
To merge profiles, select two or more customers, and then choose Merge. For more information, see Duplicates.

Test from API Explorer

Sign in to API Explorer and choose your Sandbox or Production environment. Then, call the following Customers API endpoints as needed to test your webhook:

Test using cURL

Send cURL requests to Customers API endpoints. For more information, see the following documentation:

Note

You can also send a generic test notification from the Developer Console.

You should receive notifications for customer events that you subscribe to. Square doesn't send notifications for events that fail.

For information about troubleshooting Square Webhooks, see Troubleshoot Webhooks.

Docs

Use Customer Webhooks

On this page

Overview

Requirements and limitations

How customer event notifications work

Customer profile merge events

Subscribe to customer events

To configure a webhook

To validate your webhook subscription

Did you know?

Handle customer event notifications

Notifications for customer.created events

Note

Notifications for customer.deleted events

Note

Notifications for customer.updated events

Note

Notifications for customer profile merge events

Did you know?

Example notifications from a merge operation

Test your webhooks

Note

On this page