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
endInbound 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 nameDeclares an inbound webhook source: a sender whose deliveries this resource receives, verifies, deduplicates, and handles.
Arguments
| Name | Type | Default | Docs |
|---|---|---|---|
name required | atom | The source identity stored in the inbound delivery ledger. |
Options
| Name | Type | Default | Docs |
|---|---|---|---|
source_record | module | InboundSource resource resolving provider, pause and custody keys by tenant, declaration name and cast scope. Requires record_provider_alias :on on the ledger. | |
provider | atom | The 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 | :form | Opt-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. | |
secret | any | The 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_id | any | Extractor 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_secret | any | The 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). | |
paused | any | The 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_seconds | pos_integer | Replay-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 nameDeclares 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
| Name | Type | Default | Docs |
|---|---|---|---|
name required | atom | The outbound event name (e.g. :order_paid). |
Options
| Name | Type | Default | Docs |
|---|---|---|---|
signing_mode | :legacy | :dual | :standard | :standard | Signature headers: :standard sends webhook-id, webhook-timestamp, and webhook-signature; :dual adds the legacy x-webhook-signature header; :legacy sends only that legacy header. |
subscriptions | atom | The consumer's Subscription resource module (carrying AshHooks.Subscription) this event fans out through. The dispatcher matches its rows against the event type. | |
deliveries | atom | The consumer's OutboundDelivery resource module (carrying AshHooks.OutboundDelivery) the dispatcher writes the durable per-endpoint rows into. | |
description | String.t | The catalog description of this event type: what it means and when it fires. Read back through AshHooks.Catalog for event pickers and generated docs. | |
example | String.t | A 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_schema | any | The 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. | |
version | pos_integer | 1 | The CURRENT payload version of this event type (default 1). Endpoints without a pin receive this version's bytes. |
events | atom | The 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_versions | any | The 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