Testing Stripe Webhooks + Rails 6 on your local machine

Stripe-Webhooks-Rails-6.md

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

Links

• https://stripe.com/docs/testing
  • credits to use for testing
• https://stripe.com/docs/webhooks/test
  • testing on your local machine
• https://stripe.com/docs/webhooks/best-practices
  • retry logic
  • csrf
  • event handling
• https://stripe.com/docs/billing/subscriptions/overview#requires-payment-method
  • Example: https://stripe.com/docs/billing/subscriptions/fixed-price#manage-subscription-payment-failure
• https://stripe.com/docs/billing/subscriptions/overview#requires-action
  • Example: https://stripe.com/docs/billing/subscriptions/fixed-price#manage-payment-authentication

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

1. Install Stripe CLI

brew install stripe/stripe-cli/stripe

2. Link your Stripe account

stripe login

3. 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)

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

5. 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            => "your-test-email@gmail.com",
  :password             => "your-test-password",
  :authentication       => "plain",
  :enable_starttls_auto => true,
  :openssl_verify_mode  => "none"
}

5. 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": "a-test-email@gmail.com",
        "hosted_invoice_url": "https://invoice.stripe.com/i/acct_1234/invst_5678",
      }
    }