Receive and verify webhooks

v0.0.1

Some payments finish after the buyer has left your site: a bank debit clears, a renewal fails, a refund is made in the Stripe Dashboard. The provider tells you with a signed webhook. This guide mounts the Mishka Pay endpoint, sets up Stripe to call it, chooses between thin and snapshot events, handles an event in your own code and replays what a site missed. Each Mishka CMS site gets its own endpoint address and its own signing secret, so one site's events never reach another.

Before you begin

  • Mishka Pay installed. The installer mounts the endpoint for you. See Get Started.
  • A public HTTPS address for your app. In development, use the Stripe CLI to forward events.
  • A Stripe key for the site. The endpoint also needs the site's webhook_secret, which you get when you create the Stripe endpoint.

Mount the endpoint

MishkaPay.Webhook is a Plug. It checks the signature on the raw body, so mount it before Plug.Parsers in the endpoint:

elixir
plug MishkaPay.Webhook, at: "/pay/webhooks"
plug Plug.Parsers,
  parsers: [:urlencoded, :multipart, :json],
  json_decoder: Phoenix.json_library()

The address of a site is /pay/webhooks/<provider>/<tenant>, for example https://shop.example/pay/webhooks/stripe/site-42. A project with one set of keys can use /pay/webhooks/stripe. If you mount it with forward after the parsers instead, keep the raw body with body_reader: {MishkaPay.Webhook, :read_body, ["/pay/webhooks"]} in Plug.Parsers.

Create the Stripe endpoint

Let a Mix task make the Stripe side. It creates the endpoint with every event Mishka Pay acts on, or adds the events it lacks:

bash
mix mishka_pay.stripe.webhook_endpoint \
  --url https://shop.example/pay/webhooks/stripe/site-42 \
  --tenant site-42

mix mishka_pay.stripe.webhook_endpoint \
  --url https://shop.example/pay/webhooks/stripe/site-42 \
  --tenant site-42 \
  --check

A new endpoint shows its secret once. Keep it as the site's webhook_secret in your keys plugin. --check changes nothing and fails when events are missing. Other options are --events thin|snapshot, --api v2|v1 and --connected-accounts.

In code, the same module is MishkaPay.Providers.Stripe.WebhookEndpoint. ensure(tenant, url, opts) makes or completes the endpoint, check/3 only reads it, and disable/2, enable/2 and delete/2 take its id.

For local work, run stripe listen --forward-to localhost:4000/pay/webhooks/stripe/<tenant> and put the whsec_... it prints in the site's keys.

Choose thin or snapshot events

Stripe sends events two ways, and the site picks one with the events option in its keys.

OptionDefaultChoices
events:thin:thin: a small notice that names the object. :snapshot: the event with its object as it was, in the pinned API version.
webhook_api:v2:v2: an event destination (/v2/core/event_destinations). :v1: /v1/webhook_endpoints, snapshot events only.

The webhook accepts both kinds whatever the setting. A thin event names its object only, so Mishka Pay reads what it needs and gives your code the same %MishkaPay.Event{} a snapshot event gives. Its type is the snapshot name in both modes: a thin v1.invoice.paid arrives as invoice.paid. Thin events on webhook_api: :v1 are Errors.Invalid before any request.

To move a site from snapshot to thin, make the thin destination beside the old endpoint, put its secret in webhook_secrets, then disable and delete the old one. For a while both send each change under two event ids.

Verify and answer

The endpoint checks the signature with the site's secrets and answers:

StatusWhenThe provider
200Checked, and every listener took itStops sending
400Bad or old signature (over 5 minutes), no keys or secret for the site, or an unreadable bodySends again, then gives up
404No such provider, or one without :webhookSends again
405Not a POST-
413Body over 1 MB-
500A listener failed, raised, exited or took over 15 secondsSends again later

An unknown site gets the same 400 as a bad signature, so a stranger cannot tell which sites exist. A refused message is never stored.

When you roll a Stripe secret, Stripe keeps signing with the old one for up to a day. Put the new secret in webhook_secret and the old one in webhook_secrets, a list. A message passes when any of them verifies it. Drop the old one when the window ends.

Handle an event in your code

A listener is a plugin on the mishka_pay:webhook:received event of Mishka Installer. It reads the object again from the provider, because a webhook body is never proof.

elixir
defmodule MyApp.Pay.OnEvent do
  use MishkaInstaller.Event.Hook,
    event: "mishka_pay:webhook:received"

  @impl true
  def call(%{event: %MishkaPay.Event{} = event} = state)
      when is_binary(event.payment_id) do
    {:ok, payment} =
      MishkaPay.fetch_payment(
        event.provider,
        event.payment_id,
        event.tenant
      )

    MyApp.Orders.paid(payment)
    {:reply, state}
  end

  def call(state), do: {:reply, state}
end

Supervise it like any child. Always answer {:reply, state}. If the work did not happen, answer {:reply, %{state | failed: "reason"}}. The endpoint then answers 500 and the provider sends the event again.

  • A provider may send an event twice and out of order. Keep what you did by event.id.
  • The event carries payment_id, subscription_id, dispute_id and customer_id when it names one, plus account on a Connect event.
  • Do slow work outside the request. The Ash inbox stores each event once and works it as an Oban job with retries. See Keep payments in Ash resources and Mishka CMS.

Know which events change what

MishkaPay.Providers.Stripe.handled_events/0 lists the events Mishka Pay acts on. The main groups:

Stripe eventsUpdates
checkout.session.*, payment_intent.*, charge.*, refund.*, invoice_payment.paidThe payment
charge.dispute.*The dispute and its payment
invoice.*, customer.subscription.*, subscription_schedule.*The subscription
customer.*, customer.tax_id.*, setup_intent.*, payment_method.*The customer
entitlements.active_entitlement_summary.updatedThe customer whose entitlements changed
radar.early_fraud_warning.*, review.*The payment

Transfers, payouts, application fees, credit notes, tax rates and connected-account events are verified and handed to your listener with the object id, and Mishka Pay keeps nothing for them. Any other event is verified and stored and changes nothing.

Replay what a site missed

After an outage, deliver again the events Stripe sent in the meantime. Stripe keeps 30 days of events, and the inbox keeps each event once.

bash
mix mishka_pay.replay_events \
  --provider stripe \
  --tenant site-42 \
  --since 2026-11-15T08:00:00Z

mix mishka_pay.replay_events \
  --since 2026-11-15T08:00:00Z \
  --type invoice.paid

In code: MishkaPay.replay_events("stripe", site.id, since: since) answers %{delivered: n, failed: [{id, reason}]}. MishkaPay.list_events/3 lists the events page by page. Replay the kind the site's webhook takes, so event ids match the ones the inbox kept.

Next steps