# `MishkaPay.Providers.Stripe.WebhookEndpoint`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/providers/__stripe/webhook_endpoint.ex#L5)

A site's webhook endpoint in its Stripe account, set from code instead of the Dashboard, with
the events Mishka Pay acts on. `mix mishka_pay.stripe.webhook_endpoint` runs it.

    {:ok, endpoint} = WebhookEndpoint.ensure("site-42", "https://shop.test/pay/webhooks/stripe/site-42")
    # a new endpoint answers its signing secret once: keep it as the site's `webhook_secret`

    {:ok, %{endpoint: endpoint, missing: []}} = WebhookEndpoint.check("site-42", url)

Two kinds of events, on two APIs, each a developer option: per site in its keys (`:events`,
`:webhook_api`, `MishkaPay.Credentials`), per call in `opts`:

  * `events: :thin` (the default, the format Stripe recommends): an event destination
    (`/v2/core/event_destinations`) with the thin payload and the thin events Mishka Pay maps
    (`MishkaPay.Providers.Stripe.thin_events/0`). A thin event names its object; the webhook
    reads what it needs and hands listeners the same `MishkaPay.Event` a snapshot event gives.
  * `events: :snapshot`: the events of `MishkaPay.Providers.Stripe.handled_events/0`, each with
    its object as it was, rendered in the pinned API version; on an event destination
    (`api: :v2`, the default) or on Stripe's older `/v1/webhook_endpoints` (`api: :v1`). Thin
    events never go to a `/v1/webhook_endpoints` endpoint: `events: :thin` with `api: :v1` is
    `Errors.Invalid` before any request.
  * `connected_accounts: true`: a platform's destination also takes its connected accounts'
    events (`events_from` `@self` and `@accounts`; on v1, `connect: true`); each names its
    `:account`.

The URL is an `https` address, or `http` on `localhost`; anything else is refused before any
request. `ensure/3` makes the endpoint when the account has none of that kind at that URL, or
adds the events it lacks to the one it has; it never removes events another part of the site
may need. A thin and a snapshot destination may share a URL while a site moves from one to the
other: the webhook takes both, each checked with its own secret (keep both in
`:webhook_secrets` meanwhile). `check/3` changes nothing and says which events the endpoint at
that URL does not send. `disable/2`, `enable/2` and `delete/2` take its id: `ed_...` for an
event destination, `we_...` for a v1 endpoint (Stripe lists those among its destinations too).

# `t`

```elixir
@type t() :: %MishkaPay.Providers.Stripe.WebhookEndpoint{
  api: (:v2 | :v1) | nil,
  api_version: String.t() | nil,
  enabled_events: list() | nil,
  events: (:thin | :snapshot) | nil,
  events_from: list() | nil,
  id: String.t(),
  secret: String.t() | nil,
  status: (:enabled | :disabled) | nil,
  url: String.t() | nil
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:id` | `String.t()` | yes |  |  | `validate(not_nil_value, string, not_empty)` |
| `:url` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:enabled_events` | `list()` \| `nil` | no | `[]` |  | `validate(list)` |
| `:status` | `:enabled` \| `:disabled` \| `nil` | no |  |  | `validate(enum=Atom[enabled::disabled])` |
| `:events` | `:thin` \| `:snapshot` \| `nil` | no |  |  | `validate(enum=Atom[thin::snapshot])` |
| `:api` | `:v2` \| `:v1` \| `nil` | no |  |  | `validate(enum=Atom[v2::v1])` |
| `:events_from` | `list()` \| `nil` | no | `[]` |  | `validate(list)` |
| `:api_version` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:secret` | `String.t()` \| `nil` | no |  |  | `validate(string)` |

# `builder`

# `check`

```elixir
@spec check(term(), String.t(), keyword()) ::
  {:ok, %{endpoint: t() | nil, missing: [String.t()]}}
  | {:error, Splode.Error.t()}
```

The endpoint of the asked kind at `url`, or `nil`, and the events Mishka Pay acts on that it
does not send. An endpoint that sends every event (`*`) misses none.

# `delete`

```elixir
@spec delete(term(), String.t()) :: :ok | {:error, Splode.Error.t()}
```

Deletes endpoint `id`: Stripe stops sending to it.

# `disable`

```elixir
@spec disable(term(), String.t()) :: {:ok, t()} | {:error, Splode.Error.t()}
```

Stops Stripe sending to endpoint `id` and keeps it; `enable/2` starts it again.

# `enable`

```elixir
@spec enable(term(), String.t()) :: {:ok, t()} | {:error, Splode.Error.t()}
```

Has Stripe send to endpoint `id` again.

# `enforce_keys`

# `enforce_keys`

# `ensure`

```elixir
@spec ensure(term(), String.t(), keyword()) :: {:ok, t()} | {:error, Splode.Error.t()}
```

The endpoint at `url` with every event Mishka Pay acts on: made, or its events added.

# `example`

A sample %MishkaPay.Providers.Stripe.WebhookEndpoint{} populated from defaults + type-based fallbacks.

# `keys`

# `keys`

---

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