You can configure webhook endpoints via the API to be notified about events that happen in your Stripe account or connected accounts.
Most users configure webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints.
Related guide: Setting up webhooks
Attributes
- idstring
Unique identifier for the object.
- api_
versionnullable string The API version events are rendered as for this webhook endpoint.
- descriptionnullable string
An optional description of what the webhook is used for.
- enabled_
eventsarray of strings The list of events to enable for this endpoint.
['*']
indicates that all events are enabled, except those that require explicit selection. - metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- secretstring
The endpoint’s secret, used to generate webhook signatures. Only returned at creation.
- statusstring
The status of the webhook. It can be
enabled
ordisabled
. - urlstring
The URL of the webhook endpoint.
More attributes
- objectstring
- applicationnullable string
- createdtimestamp
- livemodeboolean
{ "id": "we_1Mr5jULkdIwHu7ix1ibLTM0x", "object": "webhook_endpoint", "api_version": null, "application": null, "created": 1680122196, "description": null, "enabled_events": [ "charge.succeeded", "charge.failed" ], "livemode": false, "metadata": {}, "secret": "whsec_wRNftLajMZNeslQOP6vEPm4iVx5NlZ6z", "status": "enabled", "url": "https://example.com/my/webhook/endpoint"}
A webhook endpoint must have a url
and a list of enabled_
. You may optionally specify the Boolean connect
parameter. If set to true, then a Connect webhook endpoint that notifies the specified url
about events from all connected accounts is created; otherwise an account webhook endpoint that notifies the specified url
only about events from your account is created. You can also create webhook endpoints in the webhooks settings section of the Dashboard.
Parameters
- enabled_
eventsarray of enumsRequired The list of events to enable for this endpoint. You may specify
['*']
to enable all events, except those that require explicit selection.Possible enum valuesaccount.
application. authorized Occurs whenever a user authorizes an application. Sent to the related application only.
account.
application. deauthorized Occurs whenever a user deauthorizes an application. Sent to the related application only.
account.
external_ account. created Occurs whenever an external account is created.
account.
external_ account. deleted Occurs whenever an external account is deleted.
account.
external_ account. updated Occurs whenever an external account is updated.
account.
updated Occurs whenever an account status or property has changed.
application_
fee. created Occurs whenever an application fee is created on a charge.
application_
fee. refund. updated Occurs whenever an application fee refund is updated.
application_
fee. refunded Occurs whenever an application fee is refunded, whether from refunding a charge or from refunding the application fee directly. This includes partial refunds.
balance.
available Occurs whenever your Stripe balance has been updated (e.g., when a charge is available to be paid out). By default, Stripe automatically transfers funds in your balance to your bank account on a daily basis. This event is not fired for negative transactions.
Show 360 more - urlstringRequired
The URL of the webhook endpoint.
- api_
versionstring Events sent to this endpoint will be generated with this Stripe Version instead of your account’s default Stripe Version.
- descriptionstring
An optional description of what the webhook is used for.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata
.
More parameters
- connectboolean
Returns
Returns the webhook endpoint object with the secret
field populated.
{ "id": "we_1Mr5jULkdIwHu7ix1ibLTM0x", "object": "webhook_endpoint", "api_version": null, "application": null, "created": 1680122196, "description": null, "enabled_events": [ "charge.succeeded", "charge.failed" ], "livemode": false, "metadata": {}, "secret": "whsec_wRNftLajMZNeslQOP6vEPm4iVx5NlZ6z", "status": "enabled", "url": "https://example.com/my/webhook/endpoint"}
Updates the webhook endpoint. You may edit the url
, the list of enabled_
, and the status of your endpoint.
Parameters
- descriptionstring
An optional description of what the webhook is used for.
- enabled_
eventsarray of enums The list of events to enable for this endpoint. You may specify
['*']
to enable all events, except those that require explicit selection.Possible enum valuesaccount.
application. authorized Occurs whenever a user authorizes an application. Sent to the related application only.
account.
application. deauthorized Occurs whenever a user deauthorizes an application. Sent to the related application only.
account.
external_ account. created Occurs whenever an external account is created.
account.
external_ account. deleted Occurs whenever an external account is deleted.
account.
external_ account. updated Occurs whenever an external account is updated.
account.
updated Occurs whenever an account status or property has changed.
application_
fee. created Occurs whenever an application fee is created on a charge.
application_
fee. refund. updated Occurs whenever an application fee refund is updated.
application_
fee. refunded Occurs whenever an application fee is refunded, whether from refunding a charge or from refunding the application fee directly. This includes partial refunds.
balance.
available Occurs whenever your Stripe balance has been updated (e.g., when a charge is available to be paid out). By default, Stripe automatically transfers funds in your balance to your bank account on a daily basis. This event is not fired for negative transactions.
Show 360 more - metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata
. - urlstring
The URL of the webhook endpoint.
More parameters
- disabledboolean
Returns
The updated webhook endpoint object if successful. Otherwise, this call raises an error.
{ "id": "we_1Mr5jULkdIwHu7ix1ibLTM0x", "object": "webhook_endpoint", "api_version": null, "application": null, "created": 1680122196, "description": null, "enabled_events": [ "charge.succeeded", "charge.failed" ], "livemode": false, "metadata": {}, "status": "disabled", "url": "https://example.com/new_endpoint"}
Retrieves the webhook endpoint with the given ID.
Parameters
No parameters.
Returns
Returns a webhook endpoint if a valid webhook endpoint ID was provided. Raises an error otherwise.
{ "id": "we_1Mr5jULkdIwHu7ix1ibLTM0x", "object": "webhook_endpoint", "api_version": null, "application": null, "created": 1680122196, "description": null, "enabled_events": [ "charge.succeeded", "charge.failed" ], "livemode": false, "metadata": {}, "status": "enabled", "url": "https://example.com/my/webhook/endpoint"}