Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Webhook Endpoints 

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

Endpoints

The Webhook Endpoint object 

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 or disabled.

  • urlstring

    The URL of the webhook endpoint.

More attributes

  • objectstring

  • applicationnullable string

  • createdtimestamp

  • livemodeboolean

The Webhook Endpoint object
{
  "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"
}

Create a webhook endpoint 

A webhook endpoint must have a url and a list of enabled_events. 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 values
    account.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 369 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.

POST /v1/webhook_endpoints
curl https://api.stripe.com/v1/webhook_endpoints \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "enabled_events[]"="charge.succeeded" \
  -d "enabled_events[]"="charge.failed" \
  --data-urlencode url="https://example.com/my/webhook/endpoint"
Response
{
  "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"
}

Update a webhook endpoint 

Updates the webhook endpoint. You may edit the url, the list of enabled_events, 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 values
    account.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 369 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.

POST /v1/webhook_endpoints/:id
curl https://api.stripe.com/v1/webhook_endpoints/we_1Mr5jULkdIwHu7ix1ibLTM0x \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "enabled_events[]"="charge.succeeded" \
  -d "enabled_events[]"="charge.failed" \
  --data-urlencode url="https://example.com/new_endpoint"
Response
{
  "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"
}

Retrieve a webhook 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.

GET /v1/webhook_endpoints/:id
curl https://api.stripe.com/v1/webhook_endpoints/we_1Mr5jULkdIwHu7ix1ibLTM0x \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "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"
}