AshHooks (AshHooks v3.3.0)

Copy Markdown View Source

Receive, verify, and deduplicate incoming webhooks. Sign, deliver, retry, and track outgoing webhooks.

Attach to a resource:

use Ash.Resource,
  extensions: [AshHooks]

webhooks do
  inbound :orders do
    provider MyApp.Webhooks.OrderProvider
    secret {:app_env, [:my_app, :webhook_secret]}
    # optional: a stable event id from the decoded payload
    event_id &MyApp.Webhooks.OrderProvider.event_id/1
  end

  outbound :order_paid do
    signing_mode :dual
  end
end

Inbound use does not require Oban.

Configure consistent attribute multitenancy on every resource you enable, including attempt history and the event log. Pass :tenant or ctx[:tenant] to every entry point. AshHooks.Tenancy.resolve/2 validates the resource modules touched by each operation, including optional history and event logs. The adoption checklist explains the transition.

Summary

Types

The per-tenant sweep totals: one result per tenant (error-isolated: one tenant's failure never stops the others) plus the sum of the successful counts.

Functions

Fans an outbound event out to its subscribed endpoints. This is the outbound entry point, delegating to AshHooks.Dispatcher.dispatch/4 (the AshHooks.Ingress.ingest/4 twin).

Maps the retention prune over tenants: sequentially (routing by the resource's extension: inbound ledgers through AshHooks.Ingress.prune/2, outbound deliveries through AshHooks.Delivery.prune/2), with the same per-tenant isolation and sequencing as reap_all/2.

Calls AshHooks.Ingress.reap/2 once per entry in tenants:, in order. Each call validates its tenant, and one tenant's failure does not stop the others. Calls run sequentially so tenant sweeps do not compete for the repository's shared connection pool.

Recovers eligible outbound rows for a declaration and tenant, including interrupted enqueue, due retries, and expired send leases. Schedule this periodically for each outbound declaration and tenant; it preserves retry timing and attempt counts. See AshHooks.Dispatcher.reconcile_pending/3.

Schema validator for the paused option: the same source shapes as secret, resolving to a boolean at ingest time.

Schema validator for the secret option: accepts only secret SOURCES, rejecting a literal binary at DSL parse time.

Types

sweep_totals()

@type sweep_totals() :: %{
  results: %{optional(term()) => {:ok, non_neg_integer()} | {:error, term()}},
  total: non_neg_integer()
}

The per-tenant sweep totals: one result per tenant (error-isolated: one tenant's failure never stops the others) plus the sum of the successful counts.

Functions

dispatch(resource, name, event, opts \\ [])

@spec dispatch(module(), atom(), AshHooks.Event.t() | term(), keyword()) ::
  {:ok, [AshHooks.Dispatcher.dispatch_result()]} | {:error, term()}

Fans an outbound event out to its subscribed endpoints. This is the outbound entry point, delegating to AshHooks.Dispatcher.dispatch/4 (the AshHooks.Ingress.ingest/4 twin).

prune_all(resource, opts)

@spec prune_all(module(), keyword()) :: {:ok, sweep_totals()} | {:error, term()}

Maps the retention prune over tenants: sequentially (routing by the resource's extension: inbound ledgers through AshHooks.Ingress.prune/2, outbound deliveries through AshHooks.Delivery.prune/2), with the same per-tenant isolation and sequencing as reap_all/2.

{:ok, %{results: %{"org_a" => {:ok, 2}}, total: 2}} =
  AshHooks.prune_all(Delivery, older_than: cutoff, tenants: ["org_a"])

reap_all(resource, opts)

@spec reap_all(module(), keyword()) :: {:ok, sweep_totals()}

Calls AshHooks.Ingress.reap/2 once per entry in tenants:, in order. Each call validates its tenant, and one tenant's failure does not stop the others. Calls run sequentially so tenant sweeps do not compete for the repository's shared connection pool.

{:ok, %{results: %{"org_a" => {:ok, 3}, "org_b" => {:ok, 0}}, total: 3}} =
  AshHooks.reap_all(Ledger, tenants: ["org_a", "org_b"])

reconcile_pending(resource, name, opts \\ [])

@spec reconcile_pending(module(), atom(), keyword()) ::
  {:ok, [AshHooks.Dispatcher.dispatch_result()]} | {:error, term()}

Recovers eligible outbound rows for a declaration and tenant, including interrupted enqueue, due retries, and expired send leases. Schedule this periodically for each outbound declaration and tenant; it preserves retry timing and attempt counts. See AshHooks.Dispatcher.reconcile_pending/3.

validate_pause_source(source)

@spec validate_pause_source(term()) :: {:ok, term()} | {:error, String.t()}

Schema validator for the paused option: the same source shapes as secret, resolving to a boolean at ingest time.

validate_secret_source(source)

@spec validate_secret_source(term()) :: {:ok, term()} | {:error, String.t()}

Schema validator for the secret option: accepts only secret SOURCES, rejecting a literal binary at DSL parse time.

webhooks(body)

(macro)