AshHooks.InboundDelivery

Copy Markdown View Source

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])
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

NameTypeDefaultDocs
record_verified_facts:off | :on:offInjects 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:offInjects 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_decodermfaJSON 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:offWith :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_identitylist(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_secondspos_integer30Default claim lease duration. When a claim's lease expires the row becomes claimable again (reaper path); the stale owner can no longer mark it.