Configures an Ash resource as an outbound webhook destination, including its enable/disable state and references to signing secrets.

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

# Map a declared :active boolean instead of injecting :status.
endpoint do
  status_attribute :active
  enabled_values [true]
  disabled_value false
end

The extension injects url, status (:enabled | :disabled), and four secret references (secret_ref required, previous_secret_ref / legacy_secret_ref / legacy_previous_secret_ref for rotation and the legacy envelope). All four are AshHooks.Endpoint.SecretRef. The type rejects secret-shaped literals (whsec_ / whsk_ / whpk_ prefixed material) at cast, on every write path including consumer-defined actions: secrets live behind consumer callbacks; store references to those secrets in the endpoint rows.

With key_lifecycle :on, a standard previous key signs only before its previous_secret_retired_at, even if the retirement sweep is delayed. A roll inside an active overlap returns {:error, :overlap_active}; use expire_previous_secret/2 before rolling again immediately. An ended window permits rolling before the sweep. default_overlap_seconds configures the overlap (86,400 seconds when unset), and optional max_overlap_seconds caps both rolling and retirement scheduling from now. A stored previous reference without a retirement time is an undated state: it keeps signing, the sweep skips it, and roll_secret/2 refuses it with {:error, :previous_secret_undated}. Resolve it with schedule_previous_retirement/3 or expire_previous_secret/2. No retirement date is inferred when lifecycle tracking is adopted. Without lifecycle tracking, previous keys keep signing until their references are removed.

With legacy_key_lifecycle :on (requires key_lifecycle :on), the legacy slot follows the same lifecycle. Migrate its five nullable timestamps: legacy_secret_created_at, legacy_secret_first_used_at, legacy_previous_secret_created_at, legacy_previous_secret_first_used_at, and legacy_previous_secret_retired_at. The actions :mark_legacy_current_secret_used and :mark_legacy_previous_secret_used record first use with the same reference fence. The lifecycle helpers accept slot: :standard | :legacy, defaulting to :standard, and operate only on the selected slot. Overlap defaults and caps apply to both slots. An empty legacy incumbent installs the new key without a previous key. With the legacy option off, no legacy timestamps or actions are injected.

With status_attribute set, the extension uses that attribute instead of injecting status. The dispatcher skips endpoints whose mapped value is outside enabled_values, and the 410 auto-disable flips the mapped attribute to disabled_value. The mapped attribute must be declared by the consumer (fail-closed at compile).

The dispatcher skips non-enabled endpoints entirely (no delivery row). URL casting checks the scheme, metadata hostnames, and literal IP addresses on every write path. Send-time validation resolves hostnames and rejects nonpublic addresses; the HTTP adapter pins the validated connection address.

Govern read access to target URLs and secret references with your own resource policies. The package does not inject read policies.

Policy obligation: protect the injected :disable action wherever you expose it to application callers. The 410 rule uses it as a system write (authorize?: false). A permissive resource policy can otherwise allow callers to disable endpoints. See AshHooks.OutboundDelivery for the delivery ledger's action policy requirements.

The lifecycle helpers perform system writes (authorize?: false) after checking tenancy. Authorize application callers before exposing rolling, retirement scheduling, or immediate retirement to them.

With custodian Module, declare key_registry Resource and key_lifecycle :on. The registry uses AshHooks.KeyRegistry, the same transactional AshPostgres or AshSqlite data layer and repository for writes, with matching attribute tenancy. Migrate nullable :term columns secret_kind and previous_secret_kind; with legacy lifecycle also migrate legacy_secret_kind and legacy_previous_secret_kind. Each kind marks only its adjacent reference as custody-owned. A null kind leaves the slot under its host byte resolver. Host create and update actions refuse direct kind input. Direct reference writes require a byte resolver and never mark the slot as custody-owned. Signing reads the custodian from this resource and derives its canonical tenant inside the database transaction that reads the owner. Current and previous kinds may differ. Declare secret_resolver {module, function} for unmarked byte slots; delivery and worker resolvers are also supported. Without a resolver, an occupied unmarked slot fails permanently as key_kind_mismatch. Sender HMAC kinds are refused as kind_not_allowed before custody is called.

An unsupported tenant attribute type requires custody_tenant_key {m, f, a}. The MFA receives the cast tenant value followed by its arguments and must return equal UTF-8 binaries for tenants the database treats as equal. This equality contract belongs to the host. Compilation refuses an unsupported type without the option.

With config :ash_hooks, key_material: :custody_only, endpoint and worker secret_resolver, inbound secret and previous_secret sources, and provider webhook_signing_secret/1 and /2 implementations are refused at compile time. The setting is off by default; direct byte signing APIs remain supported.

Rolling moves kinds with their references. Expiration and ended-window displacement retire custody references in the owner's transaction; the separately scheduled registry sweep destroys them after commit. See AshHooks.KeyRegistry and the migration instructions in UPGRADING.md.

Create custody endpoints with create_with_key/3, roll with material: or generate: kind, recover a lost disclosure with reissue_secret/2, and migrate existing byte slots with adopt_keys/2. These issuing operations refuse enclosing transactions before issuing anything. Storage runs outside transactions; owner changes and registry attachment commit together. A failed attempt retires its own issues, and the registry sweep recovers crashed issues. Without secret_resolver, ordinary create actions refuse direct references.

Custody owners also receive the reserved read_custody_owner system action. It has no action filter, preparation or pagination; the resource's own base_filter still applies. Lifecycle retirement reads the persisted owner after the write and retains references held in any slot. A refusal before a write leaves an enclosing host transaction usable. A failure after a package write rolls back that write and its registry retirement together.

endpoint

Configuration of this resource as the outbound webhook endpoint.

Nested DSLs

Options

NameTypeDefaultDocs
signermoduleHost module implementing AshHooks.Signer. Runs after native signing and delivery_headers with the complete prepared request and explicit delivery context. Requires a prepared-request adapter.
signer_attributeslist(atom)[]Non-sensitive endpoint attributes selecting host signing keys and scheme. Included in the typed 410 configuration fence. Store references only.
native_signing:required | :optional:requiredWith :optional, secret_ref is nullable and native signing uses the selected mode's occupied slots only. Requires signer. Relax the database NOT NULL before enabling. Nothing unsigned is sent.
custodianmoduleOpaque-key custodian implementing AshHooks.Custody. Requires key_lifecycle :on and key_registry. Injects per-slot kind markers; migrate them before enabling. Create with create_with_key/3, roll with material: or generate:, recover disclosures with reissue_secret/2, and migrate byte slots with adopt_keys/2. Issuing operations refuse enclosing transactions.
custody_tenant_keymfaCanonical custody tenant for an otherwise unsupported tenant type: {module, function, args}, called with the cast tenant value followed by args. Must return equal UTF-8 binaries for tenants the database treats as equal. This equality contract belongs to the host.
secret_resolver{module, atom}Byte-reference resolver {module, function}. Unmarked slots use this resolver; custody slots use the custodian. Keep it during adopt_keys/2 migration. Without it, custody create actions refuse direct references and rolls require material: or generate:. Delivery and worker resolvers remain supported for byte signing. Refused with key_material: :custody_only.
key_registrymoduleHost resource using AshHooks.KeyRegistry, with the same transactional AshPostgres or AshSqlite data layer and repository for writes as this endpoint, and matching attribute tenancy.
status_attributeatomThe consumer's enable/disable attribute the package maps onto (e.g. active). When set, status is not injected; the mapped attribute is the one durable switch: the dispatcher skips endpoints whose value is outside enabled_values, and the 410 auto-disable sets it to disabled_value. The attribute must be declared in the resource's own attributes block (not another extension's injection), and enabled_values/disabled_value must be spelled out explicitly, or compilation fails closed.
version_pinning:off | :on:offWhether the payload-version pinning column is injected (default :off, leaving existing schemas untouched). With :on, the extension injects pinned_payload_version (integer, nullable). Endpoints without a pin, or pinned to the declaration's current version, receive the dispatch payload. Other pins select the matching payload_versions builder; a pin on a version with no builder fails that endpoint closed at dispatch, before any row is written. Declaring :on requires a migration for the column.
key_lifecycle:off | :on:offWhether the signing-key lifecycle columns are injected (default :off, leaving existing schemas untouched). With :on, the extension injects secret_created_at, secret_first_used_at, secret_retired_at, previous_secret_created_at, previous_secret_first_used_at, and previous_secret_retired_at (the scheduled deadline while the previous reference remains, then the actual retirement time when the reference is removed). Signing omits the standard previous key at its deadline, before the sweep removes its reference. An undated previous key keeps signing and blocks rolling until schedule_previous_retirement/3 or expire_previous_secret/2 resolves it; the sweep skips it. An active overlap refuses another roll with :overlap_active; expire the previous key before rolling again immediately, or wait for the window to end. An ended window permits rolling before the sweep. roll_secret/2, schedule_previous_retirement/3, expire_previous_secret/2 (one endpoint), and expire_previous_secrets/2 (a resource) accept optional arguments. Declaring :on requires a migration for the six columns. Timestamps only, never secret material.
legacy_key_lifecycle:off | :on:offOpts the legacy signing slot into the same lifecycle as standard keys. Requires key_lifecycle :on. Injects five nullable utc_datetime_usec columns: legacy_secret_created_at, legacy_secret_first_used_at, legacy_previous_secret_created_at, legacy_previous_secret_first_used_at, and legacy_previous_secret_retired_at. Migrate these columns before enabling. Lifecycle helpers accept slot: :legacy; the default remains slot: :standard. The same overlap gate, defaults, caps, retirement scheduling, sweep, and fenced first-use stamps apply to each slot. Signing omits a dated legacy previous key at its retirement instant.
max_overlap_secondspos_integerOptional maximum overlap for each enabled signing slot, in seconds. roll_secret/2 refuses a longer overlap with {:error, {:overlap_exceeds_max, max}}. Retirement scheduling refuses a deadline beyond that many seconds from the application clock. Must be at least the effective default_overlap_seconds.
default_overlap_secondsnon_neg_integerDefault overlap for each enabled signing slot in seconds when roll_secret/2 receives no :overlap_seconds. If unset, the default is 86,400. Zero stops the old key signing at the roll instant. Must not exceed max_overlap_seconds when a maximum is configured.
response_capture_attributes:off | :on:offWhether the per-endpoint response-capture columns are injected (default :off, leaving existing schemas untouched). With :on, the extension injects response_capture (boolean, default false), response_capture_max_bytes (integer, default 2048), response_capture_retention_seconds (integer, default 30 days), and response_header_allowlist (string array, default none). Capture is still per ROW: an endpoint records response bodies in its attempt history only when its response_capture value is true. The captured bytes are bounded by the row's cap, pass the package's redaction floor, and only allowlisted response header names are kept. Declaring :on requires a migration for the four new columns.
enabled_valueslist(any)Required with status_attribute: the mapped attribute's values that make the endpoint deliverable (e.g. [true]). A defaulted list against a boolean or custom-enum switch would silently match nothing (zero deliveries, no error), so the mapping refuses to compile without it.
disabled_valueanyREQUIRED with status_attribute: the value the injected :disable action (and the 410 auto-disable) writes to the mapped attribute (e.g. false).

endpoint.auto_disable

The sustained-failure auto-disable policy, beside the 410 rule: the health sweep (AshHooks.EndpointHealth.sweep/3) disables an endpoint whose trailing failure window meets the configured failure share with at least min_attempts of evidence, after one full warning_interval_seconds (default 60) from the stored warning time. The declaration injects the disable_warned_at marker column; migrate it with the declaration. Recovery below the warning band clears the marker. Re-enabling is an explicit application action.

Options

NameTypeDefaultDocs
failure_window_secondspos_integer3600The trailing window the failure share is computed over.
failure_shareany0.95The failed-attempt share (0 < share <= 1) at or above which the window counts as sustained failure.
min_attemptspos_integer10Minimum attempts in the window before the policy may disable.
warning_interval_secondspos_integer60Minimum seconds after the warning marker before sustained failure can disable.
warning_shareanyThe warning threshold's failure share (default: failure_share).
warning_min_attemptspos_integerMinimum attempts before a warning fires (default: half of min_attempts, at least 1).