Test a webhook endpoint

    Test that your webhook endpoint is working properly before taking it live.

    There are several ways to test your webhook endpoint:

    • Create test activity on your account
    • Manually send test events from the Dashboard
    • Use the Stripe CLI

    The first two options both require registering your endpoint with your account, which you will need to do before going live anyway, so the additional effort is low. However, you may experience firewall or tunneling issues when testing these ways, particularly when developing on localhost.

    The Stripe CLI is the easiest and fastest method for testing your webhook endpoint. With the Stripe CLI you can begin listening for–and even triggering–events without any additional configuration. This helps you easily test a webhook integration without needing to deploy your application or figure out how to open up your local environment to the public internet in order for Stripe to communicate to it.

    Step 1: Install the Stripe CLI

    To install the Stripe CLI with homebrew, run:

    brew install stripe/stripe-cli/stripe

    To install the Stripe CLI on Debian and Ubuntu-based distributions:

    1. Add Bintray’s GPG key to the apt sources keyring:
    sudo apt-key adv --keyserver hkp://pool.sks-keyservers.net:80 --recv-keys 379CE192D401AB61
    1. Add stripe-cli’s apt repository to the apt sources list:
    echo "deb https://dl.bintray.com/stripe/stripe-cli-deb stable main" | sudo tee -a /etc/apt/sources.list
    1. Update the package list:
    sudo apt-get update
    1. Install the CLI:
    sudo apt-get install stripe

    To install the Stripe CLI on RedHat and CentOS-based distributions:

    1. Add stripe-cli’s yum repository to the yum sources list:
    wget https://bintray.com/stripe/stripe-cli-rpm/rpm -O bintray-stripe-stripe-cli-rpm.repo && sudo mv bintray-stripe-stripe-cli-rpm.repo /etc/yum.repos.d/
    1. Update the package list:
    sudo yum update
    1. Install the CLI:
    sudo yum install stripe

    To install the Stripe CLI with Scoop, run:

    scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
    scoop install stripe

    To install the Stripe CLI on macOS without homebrew:

    1. Download the latest mac-os tar.gz file from https://github.com/stripe/stripe-cli/releases/latest
    2. Unzip the file: tar -xvf stripe_X.X.X_mac-os_x86_64.tar.gz

    Optionally, install the binary in a location where you can execute it globally (e.g., ~/usr/local/bin).

    To install the Stripe CLI on Linux without a package manager:

    1. Download the latest linux tar.gz file from https://github.com/stripe/stripe-cli/releases/latest
    2. Unzip the file: tar -xvf stripe_X.X.X_linux_x86_64.tar.gz
    3. Run the executable: ./stripe

    To install the Stripe CLI on Windows without Scoop, run:

    1. Download the latest windows tar.gz file from https://github.com/stripe/stripe-cli/releases/latest
    2. Unzip the stripe_X.X.X_windows_x86_64.tar.gz file
    3. Run the unzipped .exe file

    The Stripe CLI is also available as a Docker image. To install the latest version, run:

    docker run --rm -it stripe/stripe-cli latest

    After installing the Stripe CLI, pair it with your Stripe account by running stripe login in the terminal. You’ll be prompted to log in to the Stripe Dashboard to grant the Stripe CLI access to your account.

    stripe login Your pairing code is: humour-nifty-finer-magic Press Enter to open up the browser (^C to quit)

    Pairing generates a pair of secret API keys–one test mode, one live mode–that are valid for 90 days.

    Step 3: Forward events to your server

    After linking your Stripe account, you can use the Stripe CLI to listen for events via stripe listen. But to test your endpoint, you’ll want to forward received events to your server. Do so by adding the --forward-to flag when invoking stripe listen:

    stripe listen --forward-to localhost:5000/hooks Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

    Make sure to replace localhost:5000/hooks with the address and path of your webhook endpoint!

    Step 4: Trigger an event

    The Stripe CLI has a trigger command that can create certain event types for you. In a new terminal, create a payment_intent.created event:

    stripe trigger payment_intent.created

    The terminal where you ran the stripe listen command should show the event as well as the response from your server:

    stripe listen --forward-to localhost:5000/hooks Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit) INFO Received event: '{{WEBHOOK_EVENT_ID}}' [type: payment_intent.created] INFO Got response from local endpoint, status=200

    Testing from the Dashboard

    To test your webhook endpoint using the Stripe Dashboard:

    1. First add the endpoint to your account in the Dashboard’s Webhooks settings section.
    2. After adding the endpoint, click on its name in the list to access its details.
    3. On the endpoint details page, click Send test webhook.
    4. In the modal that appears, select the event type and then click Send test webhook.

    The resulting notification and your endpoint’s response are viewable by clicking on the event in the logs below. Do note that these are fake events with fake IDs (e.g., evt_1234). They cannot be fetched through the API and do not contain real, actionable data.

    Next steps

    Was this page helpful?

    Feedback about this page?

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

    On this page