Triggering actions with webhooks
How to use webhooks to respond to offline payment events.
A webhook is an HTTP endpoint that receives events from Stripe.
Webhooks allow you to be notified about payment events that happen outside your payment flow such as:
- Successful payments (
payment_
)intent. succeeded - Disputed payments (
charge.
)dispute. created - Available balance in your Stripe account (
balance.
)available
You can use the Dashboard for one-off actions like refunding a payment or updating a customer’s information, while webhooks help you scale your payments integration and process large volumes of business-critical events.
Build your own webhook
You can build a webhook handler on your own server to manage all your offline payment flows. Start by exposing an endpoint that can receive requests from Stripe and use the CLI to locally test your integration. Each request from Stripe contains an Event object with a reference to the object on Stripe that was modified.
Create a webhook endpoint
Add a new endpoint in your application. You can act on certain events by checking the type
field of the event object sent in the request body. Then you can print to standard output to make sure your webhook is working.
Start your server after adding the new endpoint.
Install and set up the Stripe CLI
For additional install options, see Get started with the Stripe CLI.
After you have the Stripe CLI installed, run stripe login
in the command line to generate a pairing code to link to your Stripe account. Press Enter to launch your browser and log in to your Stripe account to allow access. The generated API key is valid for 90 days. You can modify or delete the key under API Keys in the Dashboard.
Note
You can create a project-specific configuration by including the –project-name flag when you log in and when you run commands for that project.
Test
stripe login Your pairing code is: humour-nifty-finer-magic Press Enter to open up the browser (^C to quit)
If you want to use an existing API key, use the --api-key
flag:
stripe login --api-key
Your pairing code is: humour-nifty-finer-magic Press Enter to open up the browser (^C to quit)sk_test_4eC39HqLyjWDarjtT1zdp7dc
Test your webhook locally
Use the CLI to forward events to your local webhook endpoint using the listen
command.
Assuming your application is running on port 4242, run:
stripe listen --forward-to http://localhost:4242/webhook
In a different terminal tab, use the trigger
CLI command to trigger a mock webhook event.
stripe trigger payment_intent.succeeded
The following event appears in your listen
tab:
[200 POST] OK payment_intent.succeeded
“PaymentIntent was successful!” appears in the terminal tab your server is running.
Deploy your webhook endpoint
When you’re ready to deploy your webhook endpoint to production you need to do the following:
Use your live mode API keys and not your test mode keys.
Configure your webhook endpoint in the Stripe Dashboard or with the API.
To configure your endpoint in the Dashboard, go to your webhook settings.
Click Add endpoint and enter the URL of your endpoint, the Stripe API version, and the specific events you want Stripe to send.
Replace the webhook endpoint secret in your application with the new secret shown in the Dashboard view of your endpoint.
Your application is now ready to accept live events. For more information on configuring your webhook endpoint, see the Webhook Endpoint API. For testing in test mode, see our Development guide.