Customers
Receive notifications when customers are created, updated, deleted, or perform authentication actions.
Overview
Customer webhooks notify your application when customer accounts change or when authentication-related actions occur. Use these events to keep your systems in sync with customer data, trigger onboarding flows, and monitor account activity.
Use Cases
- Sync new customer records to your CRM
- Trigger welcome emails or onboarding workflows on registration
- Update external systems when customer profiles change
- Audit account deletions for compliance
- Build custom email verification flows
- Monitor password reset and login activity
Events
| Event | Description |
|---|---|
customer.created | A new customer account was created |
customer.updated | A customer's profile was modified |
customer.deleted | A customer account was deleted |
customer.email_verification_request | An email verification was requested |
customer.email_verification_succeeded | A customer verified their email |
customer.password_update.succeeded | A customer changed their password |
customer.PasswordResetRequestSubmitted | A password reset was requested |
customer.passwordless_login_request | A passwordless login link was requested |
customer.created
Triggered When
- A new customer registers via the SDK (checkout flow or signup form)
- A customer is created via the Core API
- A customer is created during a data import via the Platform Import Tool
- A customer account is provisioned during subscription creation
Note: The customer.created payload does not include nested subscriptions or addresses since the customer was just created and has none yet.
Payload
{
"type": "customer.created",
"id": "evt_a1b2C3d4E5f6g7H8i9J0k1L2",
"created": 1704067200,
"data": {
"object": {
"object": "customer",
"id": 67890,
"balance": 0,
"billing_email": null,
"created": "2024-01-01T00:00:00.000000Z",
"currency": null,
"default_source": null,
"delinquent": false,
"display_name": null,
"email": "[email protected]",
"email_confirm": null,
"email_hardbounce": false,
"first_name": "Jane",
"has_password": null,
"language": null,
"last_active_at": null,
"last_login_method": null,
"last_name": "Doe",
"mail_marketing": null,
"metadata": null,
"object_id": "cust_a1b2c3d4e5f6g7h8i9j0k1l2",
"organization": null,
"password_last_updated_at": null,
"phone": null,
"phone_confirm": null,
"salutation": null,
"site_id": 1,
"site_ids": [1],
"tele_marketing": null,
"title": null,
"username": null
}
}
}customer.updated
Triggered When
- A customer updates their profile via the SDK (account settings)
- A customer's profile is updated via the Core API
- An administrator edits a customer's details from the Platform
- Customer metadata is modified
Note: Password changes do not trigger customer.updated — they trigger customer.password_update.succeeded instead.
Payload
The payload includes a previous_attributes object containing only the fields that changed. It also includes nested subscriptions, shipping_addresses, and billing_addresses.
{
"type": "customer.updated",
"id": "evt_b2C3d4E5f6g7H8i9J0k1L2m3",
"created": 1704153600,
"data": {
"object": {
"object": "customer",
"id": 67890,
"balance": 0,
"billing_addresses": {
"object": "list",
"data": []
},
"billing_email": "[email protected]",
"created": "2024-01-01T00:00:00.000000Z",
"currency": "usd",
"default_source": {
"object": "source",
"id": 99999,
"object_id": "card_a1b2c3d4e5f6g7h8i9j0k1l2",
"object_gateway": "stripe",
"brand": "visa",
"country": "US",
"exp_month": 12,
"exp_year": 2030,
"funding": "credit",
"last4": "4242",
"site_ids": [1]
},
"delinquent": false,
"display_name": "Jane Doe",
"email": "[email protected]",
"email_confirm": true,
"email_hardbounce": false,
"first_name": "Jane",
"has_password": true,
"language": "en",
"last_active_at": 1704067200,
"last_login_method": "email",
"last_name": "Doe",
"mail_marketing": true,
"metadata": {"preferred_plan": "premium"},
"object_id": "cust_a1b2c3d4e5f6g7h8i9j0k1l2",
"organization": null,
"password_last_updated_at": "2024-01-01T00:00:00.000000Z",
"phone": "+1234567890",
"phone_confirm": null,
"salutation": "Ms",
"shipping_addresses": {
"object": "list",
"data": [
{
"object": "address",
"id": 12345,
"city": "New York",
"country": "US",
"line1": "123 Main Street",
"postal_code": "10001",
"state": "NY",
"type": "shipping"
}
]
},
"site_ids": [1],
"subscriptions": {
"object": "list",
"data": []
},
"tele_marketing": null,
"title": null,
"username": "janedoe"
},
"previous_attributes": {
"first_name": "Janet",
"display_name": "Janet Doe"
}
}
}customer.deleted
Triggered When
- A customer account is deleted via the Core API
- An administrator deletes a customer from the Platform
Note: When a customer is deleted, the system automatically cancels all active subscriptions and removes payment sources before firing this event.
Payload
The payload includes a previous_attributes object containing the fields that changed during the deletion process. It also includes the customer's subscriptions, shipping_addresses, and billing_addresses at the time of deletion.
{
"type": "customer.deleted",
"id": "evt_c3D4e5F6g7H8i9J0k1L2m3N4",
"created": 1704240000,
"data": {
"object": {
"object": "customer",
"id": 67890,
"balance": 0,
"billing_addresses": {
"object": "list",
"data": []
},
"billing_email": null,
"created": "2024-01-01T00:00:00.000000Z",
"currency": "usd",
"default_source": null,
"delinquent": false,
"display_name": "Jane Doe",
"email": "[email protected]",
"email_confirm": true,
"email_hardbounce": false,
"first_name": "Jane",
"has_password": true,
"language": "en",
"last_active_at": 1704067200,
"last_login_method": "email",
"last_name": "Doe",
"mail_marketing": true,
"metadata": null,
"object_id": "cust_a1b2c3d4e5f6g7h8i9j0k1l2",
"organization": null,
"password_last_updated_at": "2024-01-01T00:00:00.000000Z",
"phone": null,
"phone_confirm": null,
"salutation": null,
"shipping_addresses": {
"object": "list",
"data": []
},
"site_ids": [1],
"subscriptions": {
"object": "list",
"data": []
},
"tele_marketing": null,
"title": null,
"username": null
},
"previous_attributes": {
"default_source": {
"object": "source",
"id": 99999,
"object_id": "card_a1b2c3d4e5f6g7h8i9j0k1l2",
"object_gateway": "stripe",
"brand": "visa",
"last4": "4242"
}
}
}
}customer.email_verification_request
Triggered When
- A customer registers and email verification is required by site settings
- A customer requests a new verification email
Payload
The payload includes an email_verify_token field that can be used to build custom verification links.
{
"type": "customer.email_verification_request",
"id": "evt_d4E5f6G7h8I9j0K1l2M3n4O5",
"created": 1704067200,
"data": {
"object": {
"object": "customer",
"id": 67890,
"balance": 0,
"billing_email": null,
"created": "2024-01-01T00:00:00.000000Z",
"currency": null,
"default_source": null,
"delinquent": false,
"display_name": null,
"email": "[email protected]",
"email_confirm": null,
"email_hardbounce": false,
"email_verify_token": "abc123def456ghi789jkl012mno345",
"first_name": "Jane",
"has_password": null,
"language": null,
"last_active_at": null,
"last_login_method": null,
"last_name": "Doe",
"mail_marketing": null,
"metadata": null,
"object_id": "cust_a1b2c3d4e5f6g7h8i9j0k1l2",
"organization": null,
"password_last_updated_at": null,
"phone": null,
"phone_confirm": null,
"salutation": null,
"site_id": 1,
"site_ids": [1],
"tele_marketing": null,
"title": null,
"username": null
}
}
}customer.email_verification_succeeded
Triggered When
- A customer successfully verifies their email by clicking the verification link
Payload
{
"type": "customer.email_verification_succeeded",
"id": "evt_e5F6g7H8i9J0k1L2m3N4o5P6",
"created": 1704067200,
"data": {
"object": {
"object": "customer",
"id": 67890,
"balance": 0,
"billing_email": null,
"created": "2024-01-01T00:00:00.000000Z",
"currency": null,
"default_source": null,
"delinquent": false,
"display_name": null,
"email": "[email protected]",
"email_confirm": true,
"email_hardbounce": false,
"first_name": "Jane",
"has_password": true,
"language": null,
"last_active_at": null,
"last_login_method": null,
"last_name": "Doe",
"mail_marketing": null,
"metadata": null,
"object_id": "cust_a1b2c3d4e5f6g7h8i9j0k1l2",
"organization": null,
"password_last_updated_at": null,
"phone": null,
"phone_confirm": null,
"salutation": null,
"site_id": 1,
"site_ids": [1],
"tele_marketing": null,
"title": null,
"username": null
}
}
}customer.password_update.succeeded
Triggered When
- A customer changes their password via the SDK (account settings)
- A customer sets a new password after a password reset
Note: This event fires instead of customer.updated when the password field changes.
Payload
The payload includes a referer field indicating the URL where the password change was initiated. It also includes previous_attributes showing which fields changed.
{
"type": "customer.password_update.succeeded",
"id": "evt_f6G7h8I9j0K1l2M3n4O5p6Q7",
"created": 1704153600,
"data": {
"object": {
"object": "customer",
"id": 67890,
"balance": 0,
"billing_email": null,
"created": "2024-01-01T00:00:00.000000Z",
"currency": "usd",
"default_source": null,
"delinquent": false,
"display_name": null,
"email": "[email protected]",
"email_confirm": true,
"email_hardbounce": false,
"first_name": "Jane",
"has_password": true,
"language": null,
"last_active_at": 1704067200,
"last_login_method": "email",
"last_name": "Doe",
"mail_marketing": null,
"metadata": null,
"object_id": "cust_a1b2c3d4e5f6g7h8i9j0k1l2",
"organization": null,
"password_last_updated_at": "2024-01-02T12:00:00.000000Z",
"phone": null,
"phone_confirm": null,
"referer": "https://example.com/account/settings",
"salutation": null,
"site_ids": [1],
"tele_marketing": null,
"title": null,
"username": null
},
"previous_attributes": {
"password_last_updated_at": "2024-01-01T00:00:00.000000Z"
}
}
}customer.PasswordResetRequestSubmitted
Triggered When
- A customer requests a password reset via the SDK (forgot password flow)
Payload
The payload includes a password_reset_token that can be used to build custom password reset links, and a referer field indicating the URL where the request was initiated.
{
"type": "customer.PasswordResetRequestSubmitted",
"id": "evt_g7H8i9J0k1L2m3N4o5P6q7R8",
"created": 1704153600,
"data": {
"object": {
"object": "customer",
"id": 67890,
"balance": 0,
"billing_email": null,
"created": "2024-01-01T00:00:00.000000Z",
"currency": "usd",
"default_source": null,
"delinquent": false,
"display_name": null,
"email": "[email protected]",
"email_confirm": true,
"email_hardbounce": false,
"first_name": "Jane",
"has_password": true,
"language": null,
"last_active_at": 1704067200,
"last_login_method": "email",
"last_name": "Doe",
"mail_marketing": null,
"metadata": null,
"object_id": "cust_a1b2c3d4e5f6g7h8i9j0k1l2",
"organization": null,
"password_last_updated_at": "2024-01-01T00:00:00.000000Z",
"password_reset_token": "xyz789abc012def345ghi678jkl901",
"phone": null,
"phone_confirm": null,
"referer": "https://example.com/login",
"salutation": null,
"site_id": 1,
"site_ids": [1],
"tele_marketing": null,
"title": null,
"username": null
}
}
}customer.passwordless_login_request
Triggered When
- A customer requests a passwordless login link (magic link)
Payload
The payload includes a passwordless_token for building custom magic login links and a referer field.
{
"type": "customer.passwordless_login_request",
"id": "evt_h8I9j0K1l2M3n4O5p6Q7r8S9",
"created": 1704153600,
"data": {
"object": {
"object": "customer",
"id": 67890,
"balance": 0,
"billing_email": null,
"created": "2024-01-01T00:00:00.000000Z",
"currency": "usd",
"default_source": null,
"delinquent": false,
"display_name": null,
"email": "[email protected]",
"email_confirm": true,
"email_hardbounce": false,
"first_name": "Jane",
"has_password": true,
"language": null,
"last_active_at": 1704067200,
"last_login_method": "email",
"last_name": "Doe",
"mail_marketing": null,
"metadata": null,
"object_id": "cust_a1b2c3d4e5f6g7h8i9j0k1l2",
"organization": null,
"password_last_updated_at": "2024-01-01T00:00:00.000000Z",
"passwordless_token": "mno345pqr678stu901vwx234yz567",
"phone": null,
"phone_confirm": null,
"referer": "https://example.com/login",
"salutation": null,
"site_ids": [1],
"tele_marketing": null,
"title": null,
"username": null
}
}
}Payload Fields
Customer Object
| Field | Type | Description |
|---|---|---|
object | string | Object type identifier, always customer |
id | integer | Unique identifier for the customer |
balance | integer | Customer's account balance in cents |
billing_email | string | Billing-specific email address, if different from the main email |
created | string | ISO 8601 timestamp when the customer was created |
currency | string | Three-letter ISO currency code (lowercase) |
default_source | object | Customer's default payment source (see Default Source Object), or null |
delinquent | boolean | Whether the customer has an overdue payment |
display_name | string | Customer's display name |
email | string | Customer's primary email address |
email_confirm | boolean | Whether the customer's email is confirmed |
email_hardbounce | boolean | Whether the email address has a hard bounce recorded |
first_name | string | Customer's first name |
has_password | boolean | Whether the customer has set a password |
language | string | Customer's preferred language code |
last_active_at | integer | Unix timestamp of the customer's last activity, or null |
last_login_method | string | Last login method used: email, auth0, google, or facebook |
last_name | string | Customer's last name |
mail_marketing | boolean | Whether the customer opted into email marketing |
metadata | object | Custom key-value data attached to the customer |
object_id | string | External payment gateway customer identifier (e.g., Stripe cust_...) |
organization | object | Customer's organization, if any |
password_last_updated_at | string | ISO 8601 timestamp when the password was last changed |
phone | string | Customer's phone number |
phone_confirm | boolean | Whether the phone number is confirmed |
salutation | string | Customer's salutation (Mr, Mrs, Ms, etc.) |
site_id | integer | The site where the action occurred (only present on some events) |
site_ids | array | List of all site IDs the customer belongs to |
tele_marketing | boolean | Whether the customer opted into telemarketing |
title | string | Customer's professional title |
username | string | Customer's username |
Event-Specific Fields
These fields are added by specific events and are not part of the base customer object.
| Field | Type | Present In | Description |
|---|---|---|---|
email_verify_token | string | email_verification_request | Token for building custom email verification links |
password_reset_token | string | PasswordResetRequestSubmitted | Token for building custom password reset links |
passwordless_token | string | passwordless_login_request | Token for building custom magic login links |
referer | string | password_update.succeeded, PasswordResetRequestSubmitted, passwordless_login_request | URL where the action was initiated |
Default Source Object (Nested)
Present when the customer has a default payment method on file.
| Field | Type | Description |
|---|---|---|
object | string | Always source |
id | integer | Payment source ID |
object_id | string | External payment gateway source identifier |
object_gateway | string | Payment gateway name (e.g., stripe) |
brand | string | Card brand (e.g., visa, mastercard) |
country | string | Two-letter country code of the card issuer |
exp_month | integer | Card expiration month |
exp_year | integer | Card expiration year |
funding | string | Card funding type: credit, debit, or prepaid |
last4 | string | Last four digits of the card number |
site_ids | array | Site IDs associated with the source |
Nested Relations (customer.updated and customer.deleted only)
The customer.updated and customer.deleted events include nested lists:
| Field | Type | Description |
|---|---|---|
subscriptions | list | Customer's subscriptions at the time of the event |
shipping_addresses | list | Customer's shipping addresses |
billing_addresses | list | Customer's billing addresses |
Each nested list follows the standard list format:
{
"object": "list",
"data": [...]
}Previous Attributes
Events that include previous_attributes (customer.updated, customer.deleted, customer.password_update.succeeded) provide a previous_attributes object at the same level as the object key in data. This object contains only the fields that changed, with their values before the update.
If the customer's default_source changed, the previous source is represented as a full source object rather than just the ID.
Login Method Values
| Value | Description |
|---|---|
email | Logged in with email and password |
auth0 | Logged in via Auth0 |
google | Logged in via Google |
facebook | Logged in via Facebook |
Related
- Webhooks Overview - Setup, signatures, and configuration
Updated about 2 hours ago