Receives the webhooks providers send, as a Plug. It reads the raw body, finds the provider (and the
tenant) from the path, lets the provider check the signature with the tenant's webhook secret,
and hands the checked MishkaPay.Event to the mishka_pay:webhook:received listeners
(MishkaPay.Events.webhook_received/0). It does no work of its own.
Mounting
A signature is checked on the raw body, so the plug must see it before Plug.Parsers reads it.
Put it in the endpoint, before the parsers:
plug MishkaPay.Webhook, at: "/pay/webhooks"
plug Plug.Parsers, ...Then POST /pay/webhooks/stripe is Stripe's for a project with one set of keys, and
POST /pay/webhooks/stripe/<tenant> for one tenant's keys (MishkaPay.Credentials): give each
site's endpoint that URL in the provider's dashboard. Every other request passes through.
Mounted with forward in a router instead, the parsers have read the body already: keep a copy
with body_reader: {MishkaPay.Webhook, :read_body, ["/pay/webhooks"]} in Plug.Parsers.
Answers
The provider sends a message again until it gets a 2xx, so the status says whether to:
200the event was handed over and no listener said it failed;400a message that cannot be trusted: no keys or no webhook secret for the tenant, a signature that does not match (MishkaPay.Errors.BadSignature) or a body that cannot be read. The same answer for all of them, so a stranger cannot tell which tenants exist;404no such provider installed, or one without:webhook;413a body over 1 MB;500a checked event that a listener failed to take: it set:failed, raised, exited or took longer thanconfig :mishka_pay, webhook_timeout: ms(15 seconds).
Providers send a message again on any status but 2xx, so a tenant whose keys come later still gets its events.
Listeners
A listener is a mishka_installer plugin on mishka_pay:webhook:received. It gets %{event: event, failed: nil} and answers it with :failed set to a reason when it could not take the
event; anything but nil there counts as failed. A provider may send one event twice and in any order: a listener keeps what it did by
event.id and reads the object again from the provider. Mishka Pay's Ash inbox (stage 4) is
such a listener. The listeners run like the keys plugins, in a task that cannot take the request
down.
Telemetry
[:mishka_pay, :webhook, :start | :stop] with :provider, and on :stop the :status, the
:outcome, and for a checked event its :tenant, :type and :id. A tenant from the path is
reported only once the signature proves it, so strangers cannot fill metrics with made-up ones.
Never a body.
Summary
Functions
Hands a checked MishkaPay.Event to the mishka_pay:webhook:received listeners, as a webhook
does: :ok when they took it, or {:error, reason}. MishkaPay.replay_events/3 uses it for
events read back from the provider; the listeners keep each event once, by its id.
A Plug.Parsers :body_reader that keeps the raw body of requests under prefix, for a
webhook plug mounted with forward after the parsers.
Functions
@spec deliver(MishkaPay.Event.t()) :: :ok | {:error, term()}
Hands a checked MishkaPay.Event to the mishka_pay:webhook:received listeners, as a webhook
does: :ok when they took it, or {:error, reason}. MishkaPay.replay_events/3 uses it for
events read back from the provider; the listeners keep each event once, by its id.
@spec read_body(Plug.Conn.t(), keyword(), String.t()) :: {:ok, binary(), Plug.Conn.t()} | {:more, binary(), Plug.Conn.t()} | {:error, term()}
A Plug.Parsers :body_reader that keeps the raw body of requests under prefix, for a
webhook plug mounted with forward after the parsers.