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.

webhooks

Webhook declarations: inbound sources and outbound events for this resource.

Nested DSLs

webhooks.inbound

inbound name

Declares an inbound webhook source: a sender whose deliveries this resource receives, verifies, deduplicates, and handles.

Arguments

NameTypeDefaultDocs
name requiredatomThe source identity stored in the inbound delivery ledger.

Options

NameTypeDefaultDocs
source_recordmoduleInboundSource resource resolving provider, pause and custody keys by tenant, declaration name and cast scope. Requires record_provider_alias :on on the ledger.
provideratomThe module implementing AshHooks.Provider, for example one defined with use AshHooks.Provider, verify: [...]. Required for declaration-based keys; omit it when source_record selects the provider from its allowlist. The source name does not select a module.
body_format:json | :formOpt-in payload decoding for this route. :form decodes application/x-www-form-urlencoded names and values without interpreting bracket notation. Verification still receives the exact raw bytes. When unset, use the provider's decoder, then its body_format/0, then JSON. JSON uses the ledger's inbound_delivery.json_decoder. A generated decoder uses that policy; otherwise decode_payload/2 precedes a host-defined decode_payload/1. The request Content-Type never enables a decoder implicitly.
secretanyThe signing-secret source: an {M, f, a} callback, {:app_env, path}, a 0-arity function (app-global), or a 1-arity function (tenant -> {:ok, secret} | {:error, :no_webhook_secret}) that resolves the TENANT's secret on multitenant ledgers. Arity dispatch on literal fns is unambiguous. A literal binary is rejected at parse time. This check catches the secret passed as the option value; arguments of an MFA source are the consumer's own code.
event_idanyExtractor for the sender's event id from the decoded payload (payload -> {:ok, id} | :error). This explicit extractor takes precedence over the provider's optional event_identity/2, then event_identity/1. Any result other than {:ok, id} with a binary id uses the raw request-body digest, and an id longer than 255 bytes is stored as its SHA-256. Without an extractor or a provider callback, the raw request-body digest supplies the identity. A provider callback error fails closed rather than falling back to the digest.
previous_secretanyThe ROTATED-OUT signing secret source for this inbound declaration (the same source shapes as secret): during a rotation's overlap window, verification falls back to this key when the current one does not match; both keys verify until you remove the option (the end of your overlap window).
pausedanyThe pause switch source ({m, f, a}, {:app_env, path}, or a 0-arity fn, or tenant-aware 1-arity fn resolving to a boolean): while it resolves true, every request to this source is REFUSED with {:error, :source_paused} before verification or any write; answer 5xx from your controller to request a sender retry. Paused requests are not stored; recovery depends on the sender's retry policy. Unpause by resolving false again.
replay_window_secondspos_integerReplay-protection window for providers whose scheme carries a trustworthy timestamp. Providers without timestamps must leave this unset. A directly configured provider without a timestamp header fails compilation (AshHooks.Provider.timestamp_header/1 returns nil). A provider selected dynamically is checked at ingestion instead. The window value is passed to the provider's verify_signature/3 in the context map for scheme-specific enforcement. For a configured provider, the window overrides tolerance_seconds.

Introspection

Target: AshHooks.Inbound

webhooks.outbound

outbound name

Declares an outbound webhook event this resource emits to subscribed endpoints. The event is signed with Standard Webhooks headers by default and delivered with retry/backoff/dead-letter semantics.

Arguments

NameTypeDefaultDocs
name requiredatomThe outbound event name (e.g. :order_paid).

Options

NameTypeDefaultDocs
signing_mode:legacy | :dual | :standard:standardSignature headers: :standard sends webhook-id, webhook-timestamp, and webhook-signature; :dual adds the legacy x-webhook-signature header; :legacy sends only that legacy header.
subscriptionsatomThe consumer's Subscription resource module (carrying AshHooks.Subscription) this event fans out through. The dispatcher matches its rows against the event type.
deliveriesatomThe consumer's OutboundDelivery resource module (carrying AshHooks.OutboundDelivery) the dispatcher writes the durable per-endpoint rows into.
descriptionString.tThe catalog description of this event type: what it means and when it fires. Read back through AshHooks.Catalog for event pickers and generated docs.
exampleString.tA catalog example payload for this event type: the exact bytes (or a representative JSON document) shown in event pickers and generated docs, and sent by nothing (test sends synthesize their own payloads; wire your own sample through test_send's :payload when you want this one on the wire).
payload_schemaanyThe catalog's payload contract for this event type: a JSON-Schema map, a types module, or any term your docs renderer understands. Data for tooling only; the dispatcher never validates against it.
versionpos_integer1The CURRENT payload version of this event type (default 1). Endpoints without a pin receive this version's bytes.
eventsatomThe consumer's OutboundEvent resource module (carrying AshHooks.OutboundEvent): when set, every dispatch records the event ONCE (id, type, declared version, time, and exact payload bytes), whether or not any endpoint was enabled. The log has its own retention (AshHooks.OutboundEvent.prune/2) and answers replays (AshHooks.OutboundEvent.replay/3).
payload_versionsanyThe declared variant builders older pins resolve to: a map of version => {module, function} where f(event) :: {:ok, payload_bytes} | {:error, reason}. An endpoint pinning a version in this map, other than the current version, receives that builder's bytes instead of the dispatch payload; a pin on the current version receives the dispatch payload; a pin on any other version fails that endpoint closed (:unknown_pinned_version) before any row is written.

Introspection

Target: AshHooks.Outbound