Defines an Oban worker in the consuming application. Define the worker in
your application when Oban is installed. The package also compiles and works
without Oban; use AshHooks.Delivery.run/2 for direct delivery.
defmodule MyApp.WebhookDeliveryWorker do
use AshHooks.Worker,
deliveries: MyApp.OutboundDelivery,
endpoints: MyApp.WebhookEndpoint,
secret_resolver: {MyApp.Secrets, :webhook_secret},
queue: :webhooks,
oban: MyApp.Oban
endConsumers pass enqueue: {MyApp.WebhookDeliveryWorker, :enqueue} to
AshHooks.dispatch/4; the generated enqueue/2 is that seam.
Multitenant jobs store the row's tenant in args["tenant"]. The tenant must
survive Oban's JSON encoding unchanged: strings (UUIDs and slugs) and integers
do; an atom arrives as a string. Pair a custom parse_attribute with
tenant_from_attribute so the stored attribute and job tenant round-trip.
Use args->>'tenant', the tenant's text form, in the runtime role's job
policies. The queue engine needs separate policies over all job and peer rows.
Enqueue inserts in a bounded phase after the delivery persists. Configure
the Oban instance with the ledger's repo to share its tenant binding. When
PostgreSQL job tables use forced row security, configure the oban: instance
with queues, plugins, peer leadership, and staging disabled. Run
queues and maintenance through a second instance on an engine-role repo
with the same prefix and PostgreSQL notifier. perform/1 binds its own
tenant phases through the ledger repo. See the
row-level security guide for SQL and supervision entries.
Options:
:deliveries,:endpoints(required): the consumer's resource modules carrying theAshHooks.OutboundDelivery/AshHooks.Endpointextensions.:attempts(optional): the consumer's resource module carryingAshHooks.OutboundAttempt: when set, every delivery attempt records a durable history row (time, outcome, classified reason, HTTP status, latency, the signing key reference; per-endpoint-opt-in response capture) beside the delivery row. A history write failure never fails the send; it surfaces as[:ash_hooks, :attempt, :record_failed]telemetry.:secret_resolver(optional,{m, f}): resolves an endpoint's secret reference:f(ref) :: {:ok, secret_binary} | {:error, term}. The returned value signs the Standard Webhooks envelope (whsk_selects Ed25519;whsec_selects HMAC-SHA256); legacy envelopes, when the signing mode uses them, are signed from the endpoint'slegacy_secret_ref/legacy_previous_secret_refreferences through this same resolver. Custody slots use the endpoint resource's custodian and kind markers; no worker custodian option is needed. Omit this resolver when every slot uses custody or the endpoint declares its own byte resolver.key_material: :custody_onlyrefuses this option at compile time.:tenant_aware_secrets(optional, defaultfalse): switches the resolver contract to 2-arity:f(ref, tenant). The tenant is the run's args-threaded tenant (the delivery row's tenant, serialized at enqueue). Explicit, no arity magic: the default 1-arity contract is unchanged.:snippet_redactor({m, f}, optional): a consumer callback run on the raw captured body ahead of the package's snippet floor (domain-specific tokens need raw input). Only consulted on per-callsnippet_capture: truediagnostic runs; a crash or invalid return degrades to the sanitized summary, never raw bytes. The capture flag is not a macro option. Enable diagnostic capture through a directAshHooks.Delivery.run/2call.:destination_policy({module, function}, optional): the public send-time destination policy seam (AshHooks.DestinationPolicy): the callback receives the endpoint's URL and a context map (%{endpoint_id:, tenant:}) and returns:allow(skip the packaged SSRF gate; pair it with the adapter's validation override for destinations that check would refuse),:deny(terminaldestination_denied), or:default(the packaged tri-state check runs unchanged). A crashing or out-of-vocabulary callback is contained as a retryabledestination_policy_failed. A configured policy takes precedence over the boolean:ssrf_checkseam.:transport: the per-endpoint delivery transport resolver, a{module, function}called with the endpoint record and tenant (a function literal is refused at compile time; the direct delivery config also accepts a 2-arity function), returning anAshHooks.Transportmodule for one endpoint's deliveries (a developer's local forwarder behind a CLI "listen" command, for example), ornilto keep the HTTP adapter. The same signing, attempts, and telemetry apply. A transport module must exportrequest/5. A resolver that raises, throws, exits, or returns an invalid value refuses the attempt as a retryabletransport_resolutionfailure, without falling back to HTTP or storing or emitting error contents.:http: theAshHooks.Httpadapter (defaultAshHooks.Http.Bounded).:retryable_statuses: optional literal list of HTTP statuses/ranges that replaces the ordinary retry set. Omit it for 408/429/5xx. 2xx success, redirect refusal, and 410 disablement stay fixed.:delivery_headers: optional{module, function}called with(delivery, endpoint, tenant)before each send. Return binary header pairs. Package signing, content-type, and framing headers cannot be overridden. Callback/validation failures retry without sending.:certificate_pin: optional{module, function}called with(endpoint, tenant)each attempt. Return a pin supported byAshHooks.Http.Boundedornilfor off. Pin failure is non-retryable; a configured pin requires the bounded adapter and HTTPS. Computed host-wide pins can also be returned in:http_opts.:http_opts: adapter options as a literal keyword list or a{module, function, args}callback resolved inside each job's monitored delivery deadline. Consumer-trusted config: a literaltimeout:here must stay below:attempt_timeout(the macro refuses a larger one), andvalidate_destination: false(the test seam loopback listeners use) disables the adapter's resolve-and-pin defense, leaving only the driver's send-time destination check. The macro refuses to compile a literal bypass outside:test; never ship it to production.:oban: the Oban instance name (default the unnamed instance).:queue(default:ash_hooks),:timeout(35,000 ms), and:max_attempts(20): Oban Worker options. The job timeout must be greater than:attempt_timeout + :finalization_allowance, and Oban's:max_attemptsmust exceed:delivery_max_attempts: error-class results (attempt timeout, driver crash, endpoint read errors) consume Oban executions in step with row attempts while snooze-class results consume none, so only the row ceiling may decide dead-letter.:attempt_timeout(25,000 ms) and:finalization_allowance(5,000 ms): the driver deadline and extra send-lease interval. The attempt budget includes endpoint lookup, secret resolution, signing, destination and DNS checks, HTTP, and result persistence. A literal:http_optstimeout:must stay below:attempt_timeout(the macro refuses a larger one; an{m, f, a}bundle resolves per-perform and cannot be compile-checked). Keep application clocks synchronized because lease comparisons use the application clock.:delivery_max_attempts(default 10),:base_backoff_seconds(2),:max_backoff_seconds(3600),:retry_after_cap_seconds(86_400): the row-driven retry policy. Every budget option must be a positive integer and:max_backoff_secondsat least:base_backoff_seconds. For directAshHooks.Delivery.run/2calls,:delivery_max_attemptsbecomes:max_attempts; the other retry option names and defaults are unchanged. Omitted worker options use these defaults; explicitnilbudgets are rejected. Direct runner retry options use the defaults when omitted ornil. TheRetry-Aftercap is the maximum delay a receiver can request on each attempt. A largeRetry-Aftercan keep a delivery and its job pending for up to the cap on each attempt. The default permits 24 hours per attempt. Lower the cap when failures need to reach the attempt limit sooner. The cap does not alter exponential backoff.:runtime_config({module, function}, optional): resolves the worker-timing options PER PERFORM:f(job_args) :: keyword()returns overrides for:delivery_max_attempts,:base_backoff_seconds,:max_backoff_seconds,:retry_after_cap_seconds,:attempt_timeout, and:finalization_allowance, merged over the compiled defaults (the compiled values are defaults; overrides may be lower or higher while staying within the compiled job timeout and attempt limits). The Oban job:timeoutand:max_attemptsstay compile-time (they are Oban Worker options baked into the generated module), so the compile-time misfit checks re-run at runtime against every resolved set: an override that overruns the baked job envelope, meets or exceeds the Oban attempt ceiling, is not a positive integer, inverts the backoff ladder, collides a literal:http_optstimeout:with a lowered:attempt_timeout, or names an unknown key failsperform/1with{:error, {:invalid_runtime_config, reason}}BEFORE any delivery work; the row is untouched, Oban re-drives the job, and a[:ash_hooks, :worker, :invalid_runtime_config]telemetry event carries the reason. A callback that raises or returns a non-keyword is contained the same way (:callback_failed). Raise the compiled:timeout/:max_attemptsceilings to the maximum you will ever resolve at runtime, then lower per run.
The generated enqueue uses fields: [:args] with the complete delivery
key, delivery and endpoint resource names, source, route, endpoint/event,
and tenant keys. Uniqueness has an infinite period over runnable states
(available, scheduled, executing, and retryable). Completed,
canceled, and discarded jobs therefore permit a later recovery trigger.
Enqueue succeeds only after Oban returns a persisted runnable job whose
identity args match the request. Oban.Basic may briefly report a uniqueness
conflict without the winning job's ID while its advisory-lock peer commits;
the generated path retries that result for at most twenty 5 ms waits, then
returns {:error, :job_not_persisted}. Before insertion it binds a deferred
route once with a compare-and-set update; a different stored route returns
{:error, :dispatch_route_conflict}.
Multitenant jobs store the row's tenant in args["tenant"]. The tenant must
survive Oban's JSON encoding unchanged: strings (UUIDs and slugs) and integers
do; an atom arrives as a string. Pair a custom parse_attribute with
tenant_from_attribute so the stored attribute and job tenant round-trip.
Use args->>'tenant', the tenant's text form, in the runtime role's job
policies, alongside separate engine-role policies over all rows of
oban_jobs and oban_peers. A tenant-only policy cannot run the queue.
Summary
Functions
Resolves a worker's delivery config for one perform: when the worker
declared runtime_config: {module, function}, the callback runs with
the job's args map (string keys, tenant included when the row carries
one) and its overrides are merged over the compiled defaults. Then
the compiled-budget misfit checks re-run as runtime validation.
Functions
@spec resolve_config(keyword(), map()) :: {:ok, keyword()} | {:error, {:invalid_runtime_config, term()}}
Resolves a worker's delivery config for one perform: when the worker
declared runtime_config: {module, function}, the callback runs with
the job's args map (string keys, tenant included when the row carries
one) and its overrides are merged over the compiled defaults. Then
the compiled-budget misfit checks re-run as runtime validation.
Returns {:ok, config} (the driver-ready keyword list) or
{:error, {:invalid_runtime_config, reason}}, where reason is
:callback_failed (a crash or a non-keyword return, contained and never
raised through), {:unknown_key, key}, :not_positive_integer,
:backoff_inversion, :envelope_exceeded (the resolved attempt
deadline overruns the baked Oban job timeout, or a literal
:http_opts timeout: collides with a lowered :attempt_timeout),
or :oban_ceiling_exceeded (the resolved delivery ceiling reaches the
baked Oban job ceiling; only the row ceiling may decide dead-letter).
A rejection emits [:ash_hooks, :worker, :invalid_runtime_config] and
leaves the delivery row untouched.