Configuring the Endpoint

    Learn how to set up webhook endpoints to receive events.

    After building, testing, and deploying your webhook to production, set up the endpoint so Stripe knows where to send events.

    You can register webhook URLs for Stripe to notify you any time an event happens in your account. When the event occurs—a successful charge is made on a customer’s subscription, a transfer is paid, your account is updated, etc.—Stripe creates an Event object.

    This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. Stripe then makes an HTTP POST request to send the Event object to any endpoint URLs defined. (You define them in your account’s Webhooks settings.) You can have Stripe send a single event to multiple webhook endpoints.

    Step 1: Configure webhook settings

    Webhook endpoints are configured in the Dashboard’s webhooks settings page or programmatically using webhook endpoints.

    Add endpoints in the Dashboard

    Stripe supports two endpoint types, Account and Connect. Create an endpoint for Account unless you’ve created a Connect application.

    In the Dashboard’s Webhooks settings section, click Add endpoint to reveal a form to add a new endpoint for receiving events. You can enter any URL as the destination for events. However, this should be a dedicated page on your server that is set up to receive webhook events. You can choose to be notified of all event types, or only specific ones.

    Add endpoints with the API

    You can also programmatically create webhook endpoints. As with the form in the Dashboard, you can enter any URL as the destination for events and which event types to subscribe to. To receive events from connected accounts, use the connect parameter.

    The following example creates an endpoint that notifies you when charges succeed or fail.

    curl https://api.stripe.com/v1/webhook_endpoints \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc \
      -d url="https://example.com/my/webhook/endpoint" \
      -d enabled_events[]="charge.failed" \
      -d enabled_events[]="charge.succeeded"
    Stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    endpoint = Stripe::WebhookEndpoint.create(
      :url => "https://example.com/my/webhook/endpoint",
      :enabled_events => ["charge.failed", "charge.succeeded"]
    )
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    endpoint = stripe.WebhookEndpoint.create(
      url='https://example.com/my/webhook/endpoint',
      enabled_events=['charge.failed', 'charge.succeeded'],
    )
    \Stripe\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    $endpoint = \Stripe\WebhookEndpoint::create([
      "url" => "https://example.com/my/webhook/endpoint",
      "enabled_events" => ["charge.failed", "charge.succeeded"]
    ]);
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    Map<String, Object> webhookendpointParams = new HashMap<String, Object>();
    webhookendpointParams.put("url", "https://example.com/my/webhook/endpoint");
    webhookendpointParams.put("enabled_events", ["charge.failed", "charge.succeeded"]);
    
    WebhookEndpoint endpoint = WebhookEndpoint.create(webhookendpointParams);
    var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    const endpoint = stripe.webhookEndpoints.create({
      url: "https://example.com/my/webhook/endpoint",
      enabled_events: ["charge.failed", "charge.succeeded"]
    }, function(err, webhookEndpoint) {
      // asynchronously called
    });
    stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    params := &stripe.WebhookEndpointParams{
      URL: stripe.String("https://example.com/my/webhook/endpoint"),
      EnabledEvents: stripe.StringSlice([]string{
        "charge.failed",
        "charge.succeeded",
      }),
    }
    endpoint, err := webhookendpoint.New(params)
    StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    var options = new WebhookEndpointCreateOptions
    {
      Url = "https://example.com/my/webhook/endpoint",
      EnabledEvents = new List<String>{"charge.failed", "charge.succeeded"}
    };
    var service = new WebhookEndpointService();
    WebhookEndpoint webhookEndpoint = service.Create(options);

    Manage webhook endpoints

    If you need to update or delete a webhook endpoint, you can do so in the Dashboard’s Webhooks settings section. You also have the option of disabling a webhook endpoint temporarily. Stripe does not retry any notifications that are generated while the endpoint is disabled. Alternatively, you can manage webhook endpoints programmatically.

    Step 2: Send a test webhook event

    Next, test that your endpoint is working properly. To do this, first enable the Viewing test data option in the Dashboard.

    To view a test event, conduct an action such as creating a charge. If your endpoint is working successfully, you’ll see the event in the Dashboard. Click on the event to view further details such as the event data and the state for each webhook.

    Your current mode—whether you’re using test or live API keys—determines whether test events or live events are sent to your configured URL. If you want to send both live and test events to the same URL, you need to configure separate endpoints in the Dashboard. You can add as many URLs as you like, and Stripe supports basic access authentication.

    Alternatively, quickly test your integration using the CLI. The stripe trigger command creates a few event types for you to verify that the endpoint is working properly. To trigger an event, run:

    stripe trigger <event_type> #OR
    stripe trigger payment_intent.created
    

    Events created by the CLI are backed by real objects in the API, allowing you to test your end-to-end flow.

    Step 3: Respond to webhook events

    To acknowledge receipt of an event, your endpoint must return a 2xx HTTP status code. Acknowledge events prior to any logic that needs to take place to prevent timeouts. Your endpoint is disabled if it fails to acknowledge events over consecutive days.

    All response codes outside this range, including 3xx codes, indicate to Stripe that you did not receive the event. This does mean that a URL redirection or a “Not Modified” response is treated as a failure. Stripe ignores any other information returned in the request headers or request body.

    Step 4: Go live

    Once you’ve verified your endpoint is receiving, acknowledging, and handling events correctly, disable the Viewing test data option in the Dashboard and go through the configuration step again to configure an endpoint for your live integration. If you’re using the same endpoint for both test and live modes, the signing secret is unique to each mode. Make sure to add the new signing secret to your endpoint code if you’re checking webhook signatures.

    It’s also helpful to go through the Development Checklist to ensure a smooth transition when taking your integration live.

    More information

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page