<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshHooks

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

Attach to a resource:


<!-- not-run: This resource fragment requires host provider modules and configured secret storage. -->

    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](../tutorials/tenancy-adoption-checklist.md)
explains the transition.


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


### Nested DSLs
 * [inbound](#webhooks-inbound)
 * [outbound](#webhooks-outbound)





<h3 id="webhooks-inbound">webhooks.inbound</h3>
<!-- not-run: This Spark DSL signature requires a named declaration in an enclosing host resource. -->
```elixir
inbound name
```


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






### Arguments

<table><thead><tr><th style="text-align: left;">Name</th><th style="text-align: left;">Type</th><th style="text-align: left;">Default</th><th style="text-align: left;">Docs</th></tr></thead><tbody><tr><td style="text-align: left;"><a class="spark-required" href="#webhooks-inbound-name" id="webhooks-inbound-name"><code class="inline">name</code></a> <strong>required</strong></td><td style="text-align: left;"><code class="inline">atom</code></td><td style="text-align: left;"></td><td style="text-align: left;">The source identity stored in the inbound delivery ledger.</td></tr></tbody></table>
### Options

<table><thead><tr><th style="text-align: left;">Name</th><th style="text-align: left;">Type</th><th style="text-align: left;">Default</th><th style="text-align: left;">Docs</th></tr></thead><tbody><tr><td style="text-align: left;"><a href="#webhooks-inbound-source_record" id="webhooks-inbound-source_record"><code class="inline">source_record</code></a></td><td style="text-align: left;"><code class="inline">module</code></td><td style="text-align: left;"></td><td style="text-align: left;">InboundSource resource resolving provider, pause and custody keys by tenant, declaration name and cast scope. Requires record_provider_alias :on on the ledger.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-inbound-provider" id="webhooks-inbound-provider"><code class="inline">provider</code></a></td><td style="text-align: left;"><code class="inline">atom</code></td><td style="text-align: left;"></td><td style="text-align: left;">The module implementing <code class="inline">AshHooks.Provider</code>, for example one defined with <code class="inline">use AshHooks.Provider, verify: [...]</code>. Required for declaration-based keys; omit it when <code class="inline">source_record</code> selects the provider from its allowlist. The source name does not select a module.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-inbound-body_format" id="webhooks-inbound-body_format"><code class="inline">body_format</code></a></td><td style="text-align: left;"><code class="inline">:json | :form</code></td><td style="text-align: left;"></td><td style="text-align: left;">Opt-in payload decoding for this route. <code class="inline">:form</code> 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 <code class="inline">body_format/0</code>, then JSON. JSON uses the ledger's <code class="inline">inbound_delivery.json_decoder</code>. A generated decoder uses that policy; otherwise <code class="inline">decode_payload/2</code> precedes a host-defined <code class="inline">decode_payload/1</code>. The request Content-Type never enables a decoder implicitly.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-inbound-secret" id="webhooks-inbound-secret"><code class="inline">secret</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"></td><td style="text-align: left;">The signing-secret source: an <code class="inline">{M, f, a}</code> callback, <code class="inline">{:app_env, path}</code>, a 0-arity function (app-global), or a 1-arity function (<code class="inline">tenant -&gt; {:ok, secret} | {:error, :no_webhook_secret}</code>) 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.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-inbound-event_id" id="webhooks-inbound-event_id"><code class="inline">event_id</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"></td><td style="text-align: left;">Extractor for the sender's event id from the decoded payload (<code class="inline">payload -&gt; {:ok, id} | :error</code>). This explicit extractor takes precedence over the provider's optional <code class="inline">event_identity/2</code>, then <code class="inline">event_identity/1</code>. Any result other than <code class="inline">{:ok, id}</code> with a binary <code class="inline">id</code> 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.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-inbound-previous_secret" id="webhooks-inbound-previous_secret"><code class="inline">previous_secret</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"></td><td style="text-align: left;">The ROTATED-OUT signing secret source for this inbound declaration (the same source shapes as <code class="inline">secret</code>): 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).</td></tr><tr><td style="text-align: left;"><a href="#webhooks-inbound-paused" id="webhooks-inbound-paused"><code class="inline">paused</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"></td><td style="text-align: left;">The pause switch source (<code class="inline">{m, f, a}</code>, <code class="inline">{:app_env, path}</code>, or a 0-arity fn, or tenant-aware 1-arity fn resolving to a boolean): while it resolves <code class="inline">true</code>, every request to this source is REFUSED with <code class="inline">{:error, :source_paused}</code> 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 <code class="inline">false</code> again.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-inbound-replay_window_seconds" id="webhooks-inbound-replay_window_seconds"><code class="inline">replay_window_seconds</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"></td><td style="text-align: left;">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 (<code class="inline">AshHooks.Provider.timestamp_header/1</code> returns nil). A provider selected dynamically is checked at ingestion instead. The window value is passed to the provider's <code class="inline">verify_signature/3</code> in the context map for scheme-specific enforcement. For a configured provider, the window overrides <code class="inline">tolerance_seconds</code>.</td></tr></tbody></table>





### Introspection

Target: `AshHooks.Inbound`

<h3 id="webhooks-outbound">webhooks.outbound</h3>
<!-- not-run: This Spark DSL signature requires a named declaration in an enclosing host resource. -->
```elixir
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

<table><thead><tr><th style="text-align: left;">Name</th><th style="text-align: left;">Type</th><th style="text-align: left;">Default</th><th style="text-align: left;">Docs</th></tr></thead><tbody><tr><td style="text-align: left;"><a class="spark-required" href="#webhooks-outbound-name" id="webhooks-outbound-name"><code class="inline">name</code></a> <strong>required</strong></td><td style="text-align: left;"><code class="inline">atom</code></td><td style="text-align: left;"></td><td style="text-align: left;">The outbound event name (e.g. <code class="inline">:order_paid</code>).</td></tr></tbody></table>
### Options

<table><thead><tr><th style="text-align: left;">Name</th><th style="text-align: left;">Type</th><th style="text-align: left;">Default</th><th style="text-align: left;">Docs</th></tr></thead><tbody><tr><td style="text-align: left;"><a href="#webhooks-outbound-signing_mode" id="webhooks-outbound-signing_mode"><code class="inline">signing_mode</code></a></td><td style="text-align: left;"><code class="inline">:legacy | :dual | :standard</code></td><td style="text-align: left;"><code class="inline">:standard</code></td><td style="text-align: left;">Signature headers: <code class="inline">:standard</code> sends <code class="inline">webhook-id</code>, <code class="inline">webhook-timestamp</code>, and <code class="inline">webhook-signature</code>; <code class="inline">:dual</code> adds the legacy <code class="inline">x-webhook-signature</code> header; <code class="inline">:legacy</code> sends only that legacy header.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-outbound-subscriptions" id="webhooks-outbound-subscriptions"><code class="inline">subscriptions</code></a></td><td style="text-align: left;"><code class="inline">atom</code></td><td style="text-align: left;"></td><td style="text-align: left;">The consumer's Subscription resource module (carrying <code class="inline">AshHooks.Subscription</code>) this event fans out through. The dispatcher matches its rows against the event type.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-outbound-deliveries" id="webhooks-outbound-deliveries"><code class="inline">deliveries</code></a></td><td style="text-align: left;"><code class="inline">atom</code></td><td style="text-align: left;"></td><td style="text-align: left;">The consumer's OutboundDelivery resource module (carrying <code class="inline">AshHooks.OutboundDelivery</code>) the dispatcher writes the durable per-endpoint rows into.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-outbound-description" id="webhooks-outbound-description"><code class="inline">description</code></a></td><td style="text-align: left;"><code class="inline">String.t</code></td><td style="text-align: left;"></td><td style="text-align: left;">The catalog description of this event type: what it means and when it fires. Read back through <code class="inline">AshHooks.Catalog</code> for event pickers and generated docs.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-outbound-example" id="webhooks-outbound-example"><code class="inline">example</code></a></td><td style="text-align: left;"><code class="inline">String.t</code></td><td style="text-align: left;"></td><td style="text-align: left;">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 <code class="inline">test_send</code>'s <code class="inline">:payload</code> when you want this one on the wire).</td></tr><tr><td style="text-align: left;"><a href="#webhooks-outbound-payload_schema" id="webhooks-outbound-payload_schema"><code class="inline">payload_schema</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"></td><td style="text-align: left;">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.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-outbound-version" id="webhooks-outbound-version"><code class="inline">version</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"><code class="inline">1</code></td><td style="text-align: left;">The CURRENT payload version of this event type (default 1). Endpoints without a pin receive this version's bytes.</td></tr><tr><td style="text-align: left;"><a href="#webhooks-outbound-events" id="webhooks-outbound-events"><code class="inline">events</code></a></td><td style="text-align: left;"><code class="inline">atom</code></td><td style="text-align: left;"></td><td style="text-align: left;">The consumer's OutboundEvent resource module (carrying <code class="inline">AshHooks.OutboundEvent</code>): 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 (<code class="inline">AshHooks.OutboundEvent.prune/2</code>) and answers replays (<code class="inline">AshHooks.OutboundEvent.replay/3</code>).</td></tr><tr><td style="text-align: left;"><a href="#webhooks-outbound-payload_versions" id="webhooks-outbound-payload_versions"><code class="inline">payload_versions</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"></td><td style="text-align: left;">The declared variant builders older pins resolve to: a map of <code class="inline">version =&gt; {module, function}</code> where <code class="inline">f(event) :: {:ok, payload_bytes} | {:error, reason}</code>. An endpoint pinning a version in this map, other than the current <code class="inline">version</code>, receives that builder's bytes instead of the dispatch payload; a pin on the current <code class="inline">version</code> receives the dispatch payload; a pin on any other version fails that endpoint closed (<code class="inline">:unknown_pinned_version</code>) before any row is written.</td></tr></tbody></table>





### Introspection

Target: `AshHooks.Outbound`





<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>
