Triggering actions with webhooks

How to use webhooks to respond to offline payment events.

Overview

A webhook is an HTTP endpoint that receives events from Stripe.

Webhooks allow you to be notified about payment events that happen in the real world outside of your payment flow such as:

Successful payments (payment_intent.succeeded)
Disputed payments (charge.dispute.created)
Available balance in your Stripe account (balance.available)

While the Dashboard is great to use for one-off actions like refunding a payment or updating a customer’s information, webhooks are essential when it comes to scaling your payments integration by helping you process large volumes of business-critical events.

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.

1

Install dependencies

Install express, body-parser and the Stripe official library for Node.

2

Create endpoint

3

Handle the event

You can act on certain events by checking the type field of the event object sent in the request body. For now, let’s print to standard output to make sure our webhook is working.

4

Install Stripe CLI

Install the Stripe CLI on Debian and Ubuntu-based distributions.

5

Set up Stripe CLI

Once 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.

6

Test your webhook locally

Use the CLI to forward events to your local webhook endpoint using the listen command.

7

Test your webhook locally

In a different terminal, use the trigger CLI command to trigger a mock webhook event.

To see the list of supported events, visit the wiki.

8

Check webhook signature

Stripe includes a signature in each event’s Stripe-Signature header. This allows you to verify that the events were sent by Stripe, not by a third party. You can verify signatures either using our official libraries, or manually using your own solution.

9

Check webhook signature

server.js


// to your live secret key in production
// This example uses Express to receive webhooks


// to your live secret key in production
// This example uses Express to receive webhooks
        console.log("PaymentIntent was successful!");


// to your live secret key in production
        console.log("PaymentIntent was successful!");


// to your live secret key in production
        console.log("PaymentIntent was successful!");


// to your live secret key in production
        console.log("PaymentIntent was successful!");

Terminal

Deploy your webhook endpoint

When you are ready to deploy your webhook endpoint to production there are a couple things you need to do:

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.

That’s it! Your application is ready to accept live events. For more information on configuring your webhook endpoint, the Webhook Endpoint API, and testing in test mode see our Development guide.