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

<a id="AshHooks-InboundDelivery"></a>

Turns the consumer's resource into the inbound webhook ledger, the
durable deduplication record used by `AshHooks.Ingress`.

Attach next to the consumer's own data layer:


<!-- not-run: This ledger fragment requires host attributes, domain, and data layer configuration. -->

    use Ash.Resource,
      data_layer: AshSqlite.DataLayer,
      extensions: [AshHooks, AshHooks.InboundDelivery]

    inbound_delivery do
      scope_identity([:account_id])
    end

The extension injects the ledger fields (provider, external ids, payload +
digest, the fenced state machine's status/token/lease/attempts), the
`unique_ingest` identity spanning provider + external event id + the
declared scope slots, and the action primitives used by
`AshHooks.Ingress`. These include ingest, terminal malformed recording
(`:record_malformed`), claim/finalize/renew, payload redaction, bounded
retention, and explicit legacy identity adoption. `:record_malformed` shares
`:ingest`'s accept list and no-touch upsert identity, setting new rows to
`:failed_permanent` with error class `"malformed_payload"`.

The uniqueness identity must be backed by a unique index on the
consumer's data layer. Storage-level uniqueness preserves one ledger row
under concurrent ingests; the lease and token govern handler ownership.
Scope slots
must be non-nullable attributes: a nullable slot would make `nil` scope
values distinct on SQL unique indexes and silently break dedup for
scope-less redeliveries.

Provider identity upgrades use
`AshHooks.Ingress.plan_legacy_identity_adoption/3` and
`AshHooks.Ingress.adopt_legacy_identity/3`. Adoption keeps one deterministic
representative per canonical identity and marks every retained sibling
terminal `:superseded`; those rows cannot be reaped into handler execution.
Applying adoption requires a transaction-capable data layer and quiesced
ingress and reapers. See the ordered upgrade in `UPGRADING.md`.

The injected actions are low-level primitives: the conditional gates
(claim received rows, retryable failures, or claimed rows whose lease expired; mark/renew only by the
current token under an unexpired lease) live in the query filters that
`AshHooks.Ingress` builds. Call the driver APIs to preserve those
conditions; restrict direct access to the generated machine actions.

This ledger stores decoded provider payloads, the signed-body digest,
event IDs, and scope keys. Payloads can contain personal information.
Define read policies in your domain; the extension does not inject them.
The README's retention and security section explains these obligations.

Configure `json_decoder` to enforce a JSON policy for this ledger, such as
duplicate-member rejection. The MFA receives bytes followed by its configured
arguments and returns `{:ok, map_or_list}` or `{:error, reason}`. The default
is `{Jason, :decode, []}`. Ingress carries one decoder through each request,
including JWS protected headers, claims, and the delivered payload. Claims
and delivery decode the same bytes without caching the result.
Providers with a host-defined `decode_payload/1` need `decode_payload/2`
before this option is configured; generated decoders use the policy directly.
See `AshHooks.Provider.Conformance` for the provider test contract.


## inbound_delivery
Configuration of this resource as the inbound webhook ledger.







### 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="#inbound_delivery-record_verified_facts" id="inbound_delivery-record_verified_facts"><code class="inline">record_verified_facts</code></a></td><td style="text-align: left;"><code class="inline">:off | :on</code></td><td style="text-align: left;"><code class="inline">:off</code></td><td style="text-align: left;">Injects a nullable sensitive verified_facts map. Migrate before enabling. Provider projections are bounded JSON metadata; redaction clears them with the payload.</td></tr><tr><td style="text-align: left;"><a href="#inbound_delivery-record_provider_alias" id="inbound_delivery-record_provider_alias"><code class="inline">record_provider_alias</code></a></td><td style="text-align: left;"><code class="inline">:off | :on</code></td><td style="text-align: left;"><code class="inline">:off</code></td><td style="text-align: left;">Injects a nullable provider_alias recorded at ingest. Required by source_record declarations. Migrate the column before enabling; adopt nonterminal old receipts with InboundSource.adopt_provider_alias/4.</td></tr><tr><td style="text-align: left;"><a href="#inbound_delivery-json_decoder" id="inbound_delivery-json_decoder"><code class="inline">json_decoder</code></a></td><td style="text-align: left;"><code class="inline">mfa</code></td><td style="text-align: left;"></td><td style="text-align: left;">JSON decoding policy for every request on this ledger. Called as <code class="inline">apply(module, function, [bytes | args])</code>, returning <code class="inline">{:ok, map_or_list}</code> or <code class="inline">{:error, reason}</code>. Defaults to <code class="inline">Jason.decode/1</code>. Ingress passes the same request-scoped decoder to JWS protected-header, claims, and payload decoding. For the payload, errors, exceptions, and scalar results are malformed payloads; a refused protected header and invalid claim types are invalid signatures. Explicit declaration <code class="inline">body_format</code> still takes precedence. A provider with a host-defined <code class="inline">decode_payload/1</code> must also implement <code class="inline">decode_payload/2</code> when this option is configured. Generated <code class="inline">/1</code> callbacks are exempt; their direct calls always use the default decoder. Hand-written <code class="inline">/2</code> implementations must decode JSON only through the function supplied to them.</td></tr><tr><td style="text-align: left;"><a href="#inbound_delivery-ingress_tracking" id="inbound_delivery-ingress_tracking"><code class="inline">ingress_tracking</code></a></td><td style="text-align: left;"><code class="inline">:off | :on</code></td><td style="text-align: left;"><code class="inline">:off</code></td><td style="text-align: left;">With <code class="inline">:on</code>, injects a <code class="inline">duplicates</code> counter and attempts to store a payload-less <code class="inline">:failed_verification</code> rejection row per source, scope, and raw-body digest. Repeated rejected bodies share one row. <code class="inline">failed_verification</code> counts stored rows, not rejected requests. Duplicate accepted deliveries increment <code class="inline">duplicates</code>. Requires a migration for that column.</td></tr><tr><td style="text-align: left;"><a href="#inbound_delivery-scope_identity" id="inbound_delivery-scope_identity"><code class="inline">scope_identity</code></a></td><td style="text-align: left;"><code class="inline">list(atom)</code></td><td style="text-align: left;"><code class="inline">[]</code></td><td style="text-align: left;">Consumer-declared attributes extending the unique-ingest identity. Provider event ids are not globally unique (across accounts etc.), so the identity is <code class="inline">[:provider, :external_event_id | scope_identity]</code>. Each slot must be a non-nullable attribute on this resource (verifier rejects otherwise) and its value must be supplied on every ingest.</td></tr><tr><td style="text-align: left;"><a href="#inbound_delivery-lease_seconds" id="inbound_delivery-lease_seconds"><code class="inline">lease_seconds</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"><code class="inline">30</code></td><td style="text-align: left;">Default claim lease duration. When a claim's lease expires the row becomes claimable again (reaper path); the stale owner can no longer mark it.</td></tr></tbody></table>







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