Types of events
Use this reference to choose which events your integration handles. Each entry gives the exact type, the resource in data.object, and the change that produces the event.
To receive an event through a webhook, add its exact identifier to the endpoint's enabled_events. Wildcards are not accepted for webhook subscriptions. See the Webhook Event Catalogue for endpoint configuration, payload versions, and connected-account delivery.
Browse by resource: Accounts, Checkout Sessions, Identity verification, Invoices, Payments, Payment Intents, Payouts, Persons, Tax invoices.
Accounts
account.capability.requested
data.object is an Account Capability.
An account requests a capability. A request does not mean the capability is active; check its status before using the associated functionality.
account.capability.updated
data.object is an Account Capability.
An account capability changes, such as a change to its status or requirements. Check the updated capability to determine whether the account can use it.
account.created
data.object is an Account.
An account is created. Use its ID to associate subsequent account events with the merchant in your integration.
account.external_account.created
data.object is an External Account.
An external account, such as a bank account used for payouts, is added to an account.
account.external_account.updated
data.object is an External Account.
An external account's details change. Use the snapshot to update the payout destination information stored by your integration.
account.updated
data.object is an Account.
An account's details change. Review its capabilities and requirements when deciding whether it can accept payments or receive payouts.
Checkout Sessions
checkout_session.completed
data.object is a Checkout Session.
A Checkout Session is completed. Check payment_status and the related payment or setup resource to determine the outcome of the Checkout flow.
Identity verification
identity.verification_session.canceled
data.object is a Verification Session (object: verification_session).
A Verification Session is canceled.
identity.verification_session.created
data.object is a Verification Session (object: verification_session).
A Verification Session is created. Creation does not confirm that verification has completed.
identity.verification_session.processing
data.object is a Verification Session (object: verification_session).
A Verification Session enters processing. Wait for a subsequent status change before treating verification as complete.
identity.verification_session.redacted
data.object is a Verification Session (object: verification_session).
A Verification Session is redacted.
identity.verification_session.requires_input
data.object is a Verification Session (object: verification_session).
A Verification Session requires more input. Use its current state to determine the next step for the person completing verification.
identity.verification_session.verified
data.object is a Verification Session (object: verification_session).
A Verification Session is verified.
Invoices
invoice.paid
data.object is an Invoice.
An invoice is paid. Use the invoice ID and related subscription, when present, to reconcile the payment with your billing records.
invoice.payment_failed
data.object is an Invoice.
A payment attempt for an invoice fails. Review the invoice and payment attempt before deciding whether another collection attempt or customer action is needed. A failed attempt does not, by itself, mean the invoice is uncollectible.
Payments
payment.failed
data.object is a Payment.
A payment fails. Inspect the payment outcome before presenting a retry or another payment method to the customer.
payment.succeeded
data.object is a Payment.
A payment succeeds. Use its ID and related Payment Intent to reconcile the result with your order or billing record.
Payment Intents
payment_intent.authorized
data.object is a Payment Intent.
A Payment Intent is authorized. Check its capture method, status, and capturable amount to determine whether your integration must capture the payment.
payment_intent.captured
data.object is a Payment Intent.
A Payment Intent is captured. Use the received amount to reconcile the capture with the amount your integration expected.
Payouts
The payload is a Payout snapshot (object: payout). See Payouts for the account and destination setup.
payout.canceled
data.object is a Payout.
A payout is canceled. Review the payout snapshot before arranging a replacement.
payout.created
data.object is a Payout.
A payout is created. Creation does not confirm that funds have arrived at the destination.
payout.failed
data.object is a Payout.
A payout fails. Inspect the payout and its destination before deciding how to retry it.
payout.paid
data.object is a Payout.
A payout's status changes to paid. Use the payout ID to reconcile the result with your payout records.
payout.updated
data.object is a Payout.
A payout's details or status change.
Persons
person.created
data.object is a Person.
A person is added to an account, such as an owner, director, or representative.
person.deleted
data.object is a Person.
A person is deleted from an account. The event contains the person's final snapshot.
person.updated
data.object is a Person.
A person's details or relationship to an account change.
Tax invoices
Both events contain the public Tax Invoice summary (object: tax_invoice), including its ID, number, period, amount, currency, issue date, and download availability. See Tax Invoices for Dashboard and API downloads.
tax_invoice.available
data.object is a Tax Invoice.
The issued tax invoice's PDF is available to download. download_available is true; call download_url to obtain a temporary download link, then use the returned url before expires_at.
tax_invoice.finalized
data.object is a Tax Invoice.
A tax invoice is finalized. download_available is false at this stage. Wait for tax_invoice.available before trying to download the PDF.
Read an event
Read type to select your handler and data.object to inspect the affected resource. The payload is a snapshot of the resource when the event occurred. Its fields depend on api_version, which stays unchanged when you retrieve the event. Retrieve the resource separately if you need its current state. When supplied, data.previous_attributes contains previous values for changed fields.
The top-level account identifies the account that produced the event. For connected-account webhook deliveries, use it to associate the event with the correct merchant.
Store the Events API's id if you need to retrieve an event within its 30-day retention period. That ID can differ from the event ID in a webhook delivery. Use the List events and Retrieve an event endpoints to inspect event history. pending_webhooks reports delivery progress; the event type and resource fields determine the business outcome.
Test deliveries
webhook_endpoint.test
data.object is an empty object ({}).
An explicit webhook endpoint test produces this event. It is reserved for test deliveries and cannot be included in enabled_events. It is not part of retained Events API history.
