MishkaPay.Providers.Stripe.WebhookEndpoint (Mishka Pay v0.0.1)

Copy Markdown View Source

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).

Summary

Types

t()

The struct that builder/1 returns.

Functions

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.

Deletes endpoint id: Stripe stops sending to it.

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

Has Stripe send to endpoint id again.

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

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

Types

t()

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

FieldTypeRequiredDefaultDescriptionDerives
:idString.t()yesvalidate(not_nil_value, string, not_empty)
:urlString.t() | nilnovalidate(string)
:enabled_eventslist() | nilno[]validate(list)
:status:enabled | :disabled | nilnovalidate(enum=Atom[enabled::disabled])
:events:thin | :snapshot | nilnovalidate(enum=Atom[thin::snapshot])
:api:v2 | :v1 | nilnovalidate(enum=Atom[v2::v1])
:events_fromlist() | nilno[]validate(list)
:api_versionString.t() | nilnovalidate(string)
:secretString.t() | nilnovalidate(string)

Functions

builder(attrs_or_input, error \\ false)

check(tenant, url, opts \\ [])

@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(tenant, id)

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

Deletes endpoint id: Stripe stops sending to it.

disable(tenant, id)

@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(tenant, id)

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

Has Stripe send to endpoint id again.

enforce_keys()

enforce_keys(field)

ensure(tenant, url, opts \\ [])

@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(field)