# `MishkaPay.Webhook`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/webhook.ex#L5)

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:

  * `200` the event was handed over and no listener said it failed;
  * `400` a 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;
  * `404` no such provider installed, or one without `:webhook`;
  * `413` a body over 1 MB;
  * `500` a checked event that a listener failed to take: it set `:failed`, raised, exited or
    took longer than `config :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.

# `deliver`

```elixir
@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.

# `read_body`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
