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

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

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


<!-- not-run: This resource fragment requires a host resource with its own attributes and data layer configuration. -->

    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
 * [auto_disable](#endpoint-auto_disable)





### 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="#endpoint-signer" id="endpoint-signer"><code class="inline">signer</code></a></td><td style="text-align: left;"><code class="inline">module</code></td><td style="text-align: left;"></td><td style="text-align: left;">Host 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.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-signer_attributes" id="endpoint-signer_attributes"><code class="inline">signer_attributes</code></a></td><td style="text-align: left;"><code class="inline">list(atom)</code></td><td style="text-align: left;"><code class="inline">[]</code></td><td style="text-align: left;">Non-sensitive endpoint attributes selecting host signing keys and scheme. Included in the typed 410 configuration fence. Store references only.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-native_signing" id="endpoint-native_signing"><code class="inline">native_signing</code></a></td><td style="text-align: left;"><code class="inline">:required | :optional</code></td><td style="text-align: left;"><code class="inline">:required</code></td><td style="text-align: left;">With :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.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-custodian" id="endpoint-custodian"><code class="inline">custodian</code></a></td><td style="text-align: left;"><code class="inline">module</code></td><td style="text-align: left;"></td><td style="text-align: left;">Opaque-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.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-custody_tenant_key" id="endpoint-custody_tenant_key"><code class="inline">custody_tenant_key</code></a></td><td style="text-align: left;"><code class="inline">mfa</code></td><td style="text-align: left;"></td><td style="text-align: left;">Canonical 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.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-secret_resolver" id="endpoint-secret_resolver"><code class="inline">secret_resolver</code></a></td><td style="text-align: left;"><code class="inline">{module, atom}</code></td><td style="text-align: left;"></td><td style="text-align: left;">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.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-key_registry" id="endpoint-key_registry"><code class="inline">key_registry</code></a></td><td style="text-align: left;"><code class="inline">module</code></td><td style="text-align: left;"></td><td style="text-align: left;">Host resource using <code class="inline">AshHooks.KeyRegistry</code>, with the same transactional AshPostgres or AshSqlite data layer and repository for writes as this endpoint, and matching attribute tenancy.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-status_attribute" id="endpoint-status_attribute"><code class="inline">status_attribute</code></a></td><td style="text-align: left;"><code class="inline">atom</code></td><td style="text-align: left;"></td><td style="text-align: left;">The consumer's enable/disable attribute the package maps onto (e.g. <code class="inline">active</code>). When set, <code class="inline">status</code> is not injected; the mapped attribute is the one durable switch: the dispatcher skips endpoints whose value is outside <code class="inline">enabled_values</code>, and the 410 auto-disable sets it to <code class="inline">disabled_value</code>. The attribute must be declared in the resource's own <code class="inline">attributes</code> block (not another extension's injection), and <code class="inline">enabled_values</code>/<code class="inline">disabled_value</code> must be spelled out explicitly, or compilation fails closed.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-version_pinning" id="endpoint-version_pinning"><code class="inline">version_pinning</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 payload-version pinning 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">pinned_payload_version</code> (integer, nullable). Endpoints without a pin, or pinned to the declaration's current <code class="inline">version</code>, receive the dispatch payload. Other pins select the matching <code class="inline">payload_versions</code> builder; a pin on a version with no builder fails that endpoint closed at dispatch, before any row is written. Declaring <code class="inline">:on</code> requires a migration for the column.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-key_lifecycle" id="endpoint-key_lifecycle"><code class="inline">key_lifecycle</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 signing-key lifecycle 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">secret_created_at</code>, <code class="inline">secret_first_used_at</code>, <code class="inline">secret_retired_at</code>, <code class="inline">previous_secret_created_at</code>, <code class="inline">previous_secret_first_used_at</code>, and <code class="inline">previous_secret_retired_at</code> (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 <code class="inline">schedule_previous_retirement/3</code> or <code class="inline">expire_previous_secret/2</code> resolves it; the sweep skips it. An active overlap refuses another roll with <code class="inline">:overlap_active</code>; expire the previous key before rolling again immediately, or wait for the window to end. An ended window permits rolling before the sweep. <code class="inline">roll_secret/2</code>, <code class="inline">schedule_previous_retirement/3</code>, <code class="inline">expire_previous_secret/2</code> (one endpoint), and <code class="inline">expire_previous_secrets/2</code> (a resource) accept optional arguments. Declaring <code class="inline">:on</code> requires a migration for the six columns. Timestamps only, never secret material.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-legacy_key_lifecycle" id="endpoint-legacy_key_lifecycle"><code class="inline">legacy_key_lifecycle</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;">Opts the legacy signing slot into the same lifecycle as standard keys. Requires <code class="inline">key_lifecycle :on</code>. Injects five nullable <code class="inline">utc_datetime_usec</code> columns: <code class="inline">legacy_secret_created_at</code>, <code class="inline">legacy_secret_first_used_at</code>, <code class="inline">legacy_previous_secret_created_at</code>, <code class="inline">legacy_previous_secret_first_used_at</code>, and <code class="inline">legacy_previous_secret_retired_at</code>. Migrate these columns before enabling. Lifecycle helpers accept <code class="inline">slot: :legacy</code>; the default remains <code class="inline">slot: :standard</code>. 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.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-max_overlap_seconds" id="endpoint-max_overlap_seconds"><code class="inline">max_overlap_seconds</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"></td><td style="text-align: left;">Optional maximum overlap for each enabled signing slot, in seconds. <code class="inline">roll_secret/2</code> refuses a longer overlap with <code class="inline">{:error, {:overlap_exceeds_max, max}}</code>. Retirement scheduling refuses a deadline beyond that many seconds from the application clock. Must be at least the effective <code class="inline">default_overlap_seconds</code>.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-default_overlap_seconds" id="endpoint-default_overlap_seconds"><code class="inline">default_overlap_seconds</code></a></td><td style="text-align: left;"><code class="inline">non_neg_integer</code></td><td style="text-align: left;"></td><td style="text-align: left;">Default overlap for each enabled signing slot in seconds when <code class="inline">roll_secret/2</code> receives no <code class="inline">:overlap_seconds</code>. If unset, the default is 86,400. Zero stops the old key signing at the roll instant. Must not exceed <code class="inline">max_overlap_seconds</code> when a maximum is configured.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-response_capture_attributes" id="endpoint-response_capture_attributes"><code class="inline">response_capture_attributes</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 per-endpoint response-capture 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">response_capture</code> (boolean, default <code class="inline">false</code>), <code class="inline">response_capture_max_bytes</code> (integer, default 2048), <code class="inline">response_capture_retention_seconds</code> (integer, default 30 days), and <code class="inline">response_header_allowlist</code> (string array, default none). Capture is still per ROW: an endpoint records response bodies in its attempt history only when its <code class="inline">response_capture</code> value is <code class="inline">true</code>. 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 <code class="inline">:on</code> requires a migration for the four new columns.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-enabled_values" id="endpoint-enabled_values"><code class="inline">enabled_values</code></a></td><td style="text-align: left;"><code class="inline">list(any)</code></td><td style="text-align: left;"></td><td style="text-align: left;">Required with <code class="inline">status_attribute</code>: the mapped attribute's values that make the endpoint deliverable (e.g. <code class="inline">[true]</code>). 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.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-disabled_value" id="endpoint-disabled_value"><code class="inline">disabled_value</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"></td><td style="text-align: left;">REQUIRED with <code class="inline">status_attribute</code>: the value the injected <code class="inline">:disable</code> action (and the 410 auto-disable) writes to the mapped attribute (e.g. <code class="inline">false</code>).</td></tr></tbody></table>


<h3 id="endpoint-auto_disable">endpoint.auto_disable</h3>
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

<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="#endpoint-auto_disable-failure_window_seconds" id="endpoint-auto_disable-failure_window_seconds"><code class="inline">failure_window_seconds</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"><code class="inline">3600</code></td><td style="text-align: left;">The trailing window the failure share is computed over.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-auto_disable-failure_share" id="endpoint-auto_disable-failure_share"><code class="inline">failure_share</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"><code class="inline">0.95</code></td><td style="text-align: left;">The failed-attempt share (0 &lt; share &lt;= 1) at or above which the window counts as sustained failure.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-auto_disable-min_attempts" id="endpoint-auto_disable-min_attempts"><code class="inline">min_attempts</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"><code class="inline">10</code></td><td style="text-align: left;">Minimum attempts in the window before the policy may disable.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-auto_disable-warning_interval_seconds" id="endpoint-auto_disable-warning_interval_seconds"><code class="inline">warning_interval_seconds</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"><code class="inline">60</code></td><td style="text-align: left;">Minimum seconds after the warning marker before sustained failure can disable.</td></tr><tr><td style="text-align: left;"><a href="#endpoint-auto_disable-warning_share" id="endpoint-auto_disable-warning_share"><code class="inline">warning_share</code></a></td><td style="text-align: left;"><code class="inline">any</code></td><td style="text-align: left;"></td><td style="text-align: left;">The warning threshold's failure share (default: <code class="inline">failure_share</code>).</td></tr><tr><td style="text-align: left;"><a href="#endpoint-auto_disable-warning_min_attempts" id="endpoint-auto_disable-warning_min_attempts"><code class="inline">warning_min_attempts</code></a></td><td style="text-align: left;"><code class="inline">pos_integer</code></td><td style="text-align: left;"></td><td style="text-align: left;">Minimum attempts before a warning fires (default: half of <code class="inline">min_attempts</code>, at least 1).</td></tr></tbody></table>









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