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:
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:
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 \
--checkA 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.
| Option | Default | Choices |
|---|---|---|
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:
| Status | When | The provider |
|---|---|---|
| 200 | Checked, and every listener took it | Stops sending |
| 400 | Bad or old signature (over 5 minutes), no keys or secret for the site, or an unreadable body | Sends again, then gives up |
| 404 | No such provider, or one without :webhook | Sends again |
| 405 | Not a POST | - |
| 413 | Body over 1 MB | - |
| 500 | A listener failed, raised, exited or took over 15 seconds | Sends 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.
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}
endSupervise 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_idandcustomer_idwhen it names one, plusaccounton 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 events | Updates |
|---|---|
checkout.session.*, payment_intent.*, charge.*, refund.*, invoice_payment.paid | The 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.updated | The 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.
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.paidIn 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
- Errors and telemetry: the
[:mishka_pay, :webhook, :stop]event and its outcomes. - Test code that takes payments: send a signed event to your endpoint in a test.
- Run many sites on one Stripe platform: webhooks for connected accounts.