stripity_stripe v2.17.2

Stripe.WebhookPlug (stripity_stripe v2.17.2) View Source

Helper Plug to process webhook events and send them to a custom handler.

Installation

To handle webhook events, you must first configure your application's endpoint. Add the following to endpoint.ex, before Plug.Parsers is loaded.

plug Stripe.WebhookPlug,
  at: "/webhook/stripe",
  handler: MyAppWeb.StripeHandler,
  secret: "whsec_******"

If you have not yet added a webhook to your Stripe account, you can do so by visiting Developers > Webhooks in the Stripe dashboard. Use the route you configured in the endpoint above and copy the webhook secret into your app's configuration.

Supported options

  • at: The URL path your application should listen for Stripe webhooks on. Configure this to match whatever you set in the webhook.
  • handler: Custom event handler module that accepts Stripe.Event structs and processes them within your application. You must create this module.
  • secret: Webhook secret starting with whsec_ obtained from the Stripe dashboard. This can also be a function or a tuple for runtime configuration.
  • tolerance: Maximum age (in seconds) allowed for the webhook event. See Stripe.Webhook.construct_event/4 for more information.

Handling events

You will need to create a custom event handler module to handle events.

Your event handler module should implement the Stripe.WebhookHandler behavior, defining a handle_event/1 function which takes a Stripe.Event struct and returns either {:ok, term} or :ok. This will mark the event as successfully processed. Alternatively handler can signal an error by returning :error or {:error, reason} tuple, where reason is an atom or a string. HTTP status code 400 will be used for errors.

Example 

# lib/myapp_web/stripe_handler.ex

defmodule MyAppWeb.StripeHandler do
  @behaviour Stripe.WebhookHandler

  @impl true
  def handle_event(%Stripe.Event{type: "charge.succeeded"} = event) do
    # TODO: handle the charge.succeeded event
  end

  @impl true
  def handle_event(%Stripe.Event{type: "invoice.payment_failed"} = event) do
    # TODO: handle the invoice.payment_failed event
  end

  # Return HTTP 200 for unhandled events
  @impl true
  def handle_event(_event), do: :ok
end

Configuration

You can configure the webhook secret in your app's own config file. For example:

config :myapp,
  # [...]
  stripe_webhook_secret: "whsec_******"

You may then include the secret in your endpoint:

plug Stripe.WebhookPlug,
  at: "/webhook/stripe",
  handler: MyAppWeb.StripeHandler,
  secret: Application.get_env(:myapp, :stripe_webhook_secret)

Runtime configuration

If you're loading config dynamically at runtime (eg with runtime.exs or an OTP app) you must pass a tuple or function as the secret.

# With a tuple
plug Stripe.WebhookPlug,
  at: "/webhook/stripe",
  handler: MyAppWeb.StripeHandler,
  secret: {Application, :get_env, [:myapp, :stripe_webhook_secret]}

# Or, with a function
plug Stripe.WebhookPlug,
  at: "/webhook/stripe",
  handler: MyAppWeb.StripeHandler,
  secret: fn -> Application.get_env(:myapp, :stripe_webhook_secret) end