Testing Stripe Webhooks + Rails 6 on your local machine

The document describes how to test Stripe Webhooks with Ruby On Rails on your local machine. Information in this document is current as of 4/22/2021.

Rails 6.1.3.1
Ruby 2.7.3p183
Stripe 1.5.14

Test Credit Cards

Valid card that does not require authentication 4242 4242 4242 4242
Valid card that requires authentication 4000 0027 6000 3184
Attaching card to customer, but charging the card fails 4000 0000 0000 0341
More credit cards can be found at https://stripe.com/docs/testing to test other scenarios
Use any 3 digits for CVV code.
Use any future date for Expiration Date
Use any 5 digits for Zip Code

Setup

Install Stripe CLI

brew install stripe/stripe-cli/stripe

Link your Stripe account

stripe login

In one terminal, tell Stripe to forward events to your local machine. The /api/webhooks/stripe endpoint is located in the Rails app at app/controllers/api/webhooks/stripe_controller.rb. Your location may be different.

stripe listen --forward-to localhost:3000/api/webhooks/stripe
> Ready! Your webhook signing secret is whsec_1234 (^C to quit)

Update your .env variables. Use the webhook signing secret from the previous step. Find the Publishable Key and Secret Key at https://dashboard.stripe.com/test/apikeys.

STRIPE_PUBLISHABLE_KEY=replace_me
STRIPE_SECRET_KEY=replace_me
STRIPE_WEBHOOK_SECRET=whsec_1234

Configure the application to send email notifications.

# config/environments/development.rb

config.action_mailer.default_url_options = {host: "localhost", port: 3000}
config.action_mailer.delivery_method = :smtp
config.action_mailer.raise_delivery_errors = true
config.action_mailer.perform_deliveries = true
config.action_mailer.perform_caching = false

config.action_mailer.smtp_settings = {
  :address              => "smtp.gmail.com",
  :domain               => "smtp-relay.gmail.com",
  :port                 => 587,
  :user_name            => "[email protected]",
  :password             => "your-test-password",
  :authentication       => "plain",
  :enable_starttls_auto => true,
  :openssl_verify_mode  => "none"
}

In a second terminal, start the Rails application

rails s -p 3000

Testing

Now that setup is complete, you can begin testing your the webhooks.

Manually testing specific webhooks

In a third terminal, trigger an event.
- stripe trigger payment_intent.created

Test payment methods

Attempt to pay for a product or subscription using your Rails application.
Use a credit card for a scenario you'd like to test.
- Test credit cards can be found here: https://stripe.com/docs/testing

Notifications

Email notifications for invoice.payment_failed or invoice.payment_action_required should include a link to the hosted_invoice_url found in the webhook event invoice object.

When a user clicks on this link after opening the email notification, they will be taken to a Stripe hosted page that will determine what action the user should take.

If a payment fails, they will be shown a form to update their credit card information.
If a payment requires a user to confirm their payment, they will be shown a form to confirm their payment.

Example event data to find the hosted_invoice_url.

{
  "object": {
    "id": "in_2222",
    "object": "invoice",
    "account_country": "US",
    "amount_due": 2000,
    "amount_paid": 0,
    "amount_remaining": 2000,
    "billing_reason": "subscription_create",
    "charge": "ch_11111",
    "collection_method": "charge_automatically",
    "created": 1619120729,
    "currency": "usd",
    "custom_fields": null,
    "customer": "cus_JLmHzXUHGfxmhC",
    "customer_address": null,
    "customer_email": "[email protected]",
    "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1234/invst_5678",
  }
}

kany/Stripe-Webhooks-Rails-6.md