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:
use Ash.Resource,
data_layer: AshSqlite.DataLayer,
extensions: [AshHooks, AshHooks.InboundDelivery]
inbound_delivery do
scope_identity([:account_id])
endThe 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
| Name | Type | Default | Docs |
|---|---|---|---|
record_verified_facts | :off | :on | :off | Injects a nullable sensitive verified_facts map. Migrate before enabling. Provider projections are bounded JSON metadata; redaction clears them with the payload. |
record_provider_alias | :off | :on | :off | 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. |
json_decoder | mfa | JSON decoding policy for every request on this ledger. Called as apply(module, function, [bytes | args]), returning {:ok, map_or_list} or {:error, reason}. Defaults to Jason.decode/1. 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 body_format still takes precedence. A provider with a host-defined decode_payload/1 must also implement decode_payload/2 when this option is configured. Generated /1 callbacks are exempt; their direct calls always use the default decoder. Hand-written /2 implementations must decode JSON only through the function supplied to them. | |
ingress_tracking | :off | :on | :off | With :on, injects a duplicates counter and attempts to store a payload-less :failed_verification rejection row per source, scope, and raw-body digest. Repeated rejected bodies share one row. failed_verification counts stored rows, not rejected requests. Duplicate accepted deliveries increment duplicates. Requires a migration for that column. |
scope_identity | list(atom) | [] | Consumer-declared attributes extending the unique-ingest identity. Provider event ids are not globally unique (across accounts etc.), so the identity is [:provider, :external_event_id | scope_identity]. Each slot must be a non-nullable attribute on this resource (verifier rejects otherwise) and its value must be supplied on every ingest. |
lease_seconds | pos_integer | 30 | 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. |