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

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

Turns the consumer's resource into the outbound delivery ledger: a durable,
deduplicated obligation recording that an event must be delivered to an
endpoint (the outbound twin of `AshHooks.InboundDelivery`). Sends remain
at-least-once, and receivers deduplicate retries by webhook id.


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

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

    # optional: rename the exact-bytes column when `payload` is
    # reserved by the consumer's domain (e.g. a sole payload store)
    outbound_delivery do
      payload_attribute :event_bytes
    end

The extension injects the delivery fields (`event_uuid`, the webhook
id, immutable across retries; the exact `payload` bytes to sign;
`endpoint_id`/`subscription_id`; immutable `dispatch_source` and
`dispatch_route`; the lifecycle `status`; accounting `attempts`; fenced
send and enqueue tokens/leases; the durable 410 endpoint snapshot;
the machine-written `response_status`/`response_snippet`/
`next_attempt_at`; bounded `last_error`) and the `unique_delivery`
identity on `[:endpoint_id, :event_uuid]`. The ownership fields default to
explicit direct/unbound markers so existing direct callers of `:dispatch`
remain valid; the first authorized direct driver and worker route bind them
once with compare-and-set updates. Host declarations that replace these
fields with incompatible types, nullability, defaults, or writable machine
fields fail resource verification. Oban admission includes this
receiver identity plus the complete row key, source, route, and tenant.
The extension also injects the machine primitives `:dispatch` (no-touch unique upsert, the
`:ingest` mirror) and `:mark_enqueue_failed`.

Storage-level uniqueness on `unique_delivery` is the idempotency
primitive: the consumer's migration must carry the matching unique
index.

`response_status`, `response_snippet` (the no-body summary by default:
status + allowlisted content-type token, with the `[captured]`-marked,
redacted body only on the runtime's per-call opt-in), and `next_attempt_at`
are `writable?: false`; no consumer create/update input accepts them;
they reach the ledger only
as arguments of the runtime's machine primitives (`:mark_succeeded`,
`:mark_send_failed`), fenced to the current attempt. Request and response
headers are not stored on this resource.

Rows contain the exact payload bytes you dispatched. Define read policies
in your domain; the extension does not inject them.

Policy obligation: the package injects write actions; your application
defines their authorization.
Under a permissive base policy fragment (an authorize-if-active-member
fallback), every actor could otherwise reach the machine primitives:
mark a delivery succeeded (suppressing a real send), dead-letter one,
requeue, or prune the ledger. The injected write actions on this
resource: `:dispatch`, `:mark_enqueue_failed`, `:bind_dispatch_source`,
`:bind_dispatch_route`, `:claim_enqueue`, `:release_enqueue`, `:requeue`, `:prune`
(the retention destroy, omittable via `prune_action :none`),
`:mark_sending`, `:mark_succeeded`, `:mark_send_failed`,
`:mark_disable_pending`, `:finalize_disable`. Cover each
with an action-specific policy (the runtime's internal calls run
`authorize?: false` and never consult them), or ensure no actor-facing
surface (json_api/graphql/code_interface/admin) exposes the resource.
The runtime writes through these actions; a policy per action is
the complete seam.


## outbound_delivery
Configuration of this resource as the outbound delivery 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="#outbound_delivery-payload_attribute" id="outbound_delivery-payload_attribute"><code class="inline">payload_attribute</code></a></td><td style="text-align: left;"><code class="inline">atom</code></td><td style="text-align: left;"><code class="inline">:payload</code></td><td style="text-align: left;">The attribute name for the exact payload bytes the dispatcher persists and the delivery runtime signs and sends (default <code class="inline">:payload</code>). Rename it when the consumer's domain reserves <code class="inline">payload</code> for its own sole payload store: the injected column, the <code class="inline">:dispatch</code> accept list, and every signing/sending read follow the configured name. Must not collide with another injected delivery field (fail-closed at compile).</td></tr><tr><td style="text-align: left;"><a href="#outbound_delivery-test_tracking" id="outbound_delivery-test_tracking"><code class="inline">test_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;">Whether the <code class="inline">test</code> flag column is injected (default <code class="inline">:off</code>, leaving existing schemas untouched). With <code class="inline">:on</code>, the extension injects <code class="inline">test</code> (boolean, default <code class="inline">false</code>): rows created by <code class="inline">AshHooks.Delivery.test_send/2</code> carry <code class="inline">test: true</code>, attempt history rows flag themselves the same way, and both list queries filter on <code class="inline">test:</code>; test sends appear in the delivery log, clearly marked. Requires a migration for the column.</td></tr><tr><td style="text-align: left;"><a href="#outbound_delivery-resend_tracking" id="outbound_delivery-resend_tracking"><code class="inline">resend_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;">Whether the resend-tracking columns are injected (default <code class="inline">:off</code>, leaving existing schemas untouched). With <code class="inline">:on</code>, the extension injects <code class="inline">resend_baseline</code> (the attempt number where the current retry ladder started), <code class="inline">resend_count</code>, <code class="inline">last_resend_by</code>, and <code class="inline">last_resend_at</code>, the machine-written columns behind <code class="inline">AshHooks.Delivery.resend/2</code> and <code class="inline">replay/2</code> (both fail closed with a named error on resources without them). Declaring <code class="inline">:on</code> requires a migration for the four columns.</td></tr><tr><td style="text-align: left;"><a href="#outbound_delivery-prune_action" id="outbound_delivery-prune_action"><code class="inline">prune_action</code></a></td><td style="text-align: left;"><code class="inline">:destroy | :none</code></td><td style="text-align: left;"><code class="inline">:destroy</code></td><td style="text-align: left;">Whether the retention <code class="inline">destroy :prune</code> action is injected (default <code class="inline">:destroy</code>). With <code class="inline">:none</code>, this extension does not inject the <code class="inline">:prune</code> destroy action; application-defined destroy actions remain. <code class="inline">AshHooks.Delivery.prune/2</code> then returns a named error. The application owns deletion through any separately defined actions.</td></tr></tbody></table>







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