Stripe-events NPM

stripe-events

NOTICE: Stripe Events is a PRE-RELEASE project and has not been released to the public. Please provide your feedback by sending an email to auchenberg@stripe.com or open issues here on GitHub. Don't talk about this project in public.

Stripe Events is JavaScript library that abstracts the complexity of http transport and webhooks signing away, by letting you subscribe to webhooks events in a event-emitter way.

Stripe Events works as a standalone endpoint, as HTTP middleware and as Express middleware.

Stripe Events is an experimental project with no guaranteed support built by Stripe to explore ways to make the developer experience for webhooks better.

We are eager to hear your feedback, so please open issues, tweet at us or email us directly at dev-feedback@stripe.com.

Getting started

npm install stripe-events

Using the stripe-events abstraction

let StripeEvents = require('stripe-events');

var stripeEvents = new StripeEvents({
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
});

// Subscribe to a specific event.
stripeEvents.on('payment_intent.created', (event) => {
  console.log('Received a payment_intent.created event', event);
  try {
    // Make API request to update my database
  } catch (err) {
    throw new Error('Something went wrong while handling my event');
  }
});

// Subscribe to all events and handle things yourself
stripeEvents.onAny((eventName, event) => {
  switch (eventName) {
    case 'invoice.created':
      console.log('invoice.created');
      break;

    case 'customer.subscription.updated':
      console.log('customer.subscription.updated');
      break;
  }
});

Using in standalone mode

See examples/standalone.js

Output:

> Stripe events is listening on:
>  local:  http://localhost:3000/stripe-events
>  public: http://104.232.117.134:3000/stripe-events
>
> Please register this endpoint in your Stripe dashboard.
>
> Awaiting incoming events...

Using in cloud environments

Go to your Stripe Dashboard and register your stripe-events endpoint by using your public IP https://<public IP>/stripe-events.

Events should now arrive.

Local debugging with stripe-cli

When running locally or in development you can use the Stripe CLI to forward webhook events to your local machine. Simply run

stripe listen --forward-to=localhost:3000/stripe-events

and start your Node server, and the events should start flowing to your machine.

Exception handling

You can throw Error objects from your event handlers to indicate that something went wrong while handling the event. This alters the response to Stripe by sending a HTTP 400 together with the error object serialized as JSON.

Stripe will re-try to deliver the event per our webhooks policy.

// Something went wrong while handling my event
stripeEvents.on('payment_intent.created', (event) => {
  console.log('Received a payment_intent.created event', event);
  throw new Error('Something went wrong. Let me THROW an error');
});