# AshHooks v3.2.0 - Table of Contents

> Webhooks for Ash Framework: verify and deduplicate inbound webhooks from any sender, and sign and deliver outbound webhooks.

## Pages

- [AshHooks](readme.md)
- [Changelog](changelog.md)
- [AshHooks usage rules](usage-rules.md)
- [Upgrading](upgrading.md)
- [Security policy](security.md)
- [Contributing](contributing.md)

- Tutorials
  - [Get started](get-started-1.md)
  - [Key custody and lifecycle](key-custody.md)
  - [Row-level security](row-security.md)
  - [Multi-tenant adoption checklist](tenancy-adoption-checklist.md)
  - [Verify any sender](verify-any-sender.md)

- Livebooks
  - [AshHooks guided tour](get-started-2.md)

- DSLs
  - [AshHooks.Endpoint](dsl-ashhooks-endpoint.md)
  - [AshHooks.InboundDelivery](dsl-ashhooks-inbounddelivery.md)
  - [AshHooks.InboundSource](dsl-ashhooks-inboundsource.md)
  - [AshHooks.KeyRegistry](dsl-ashhooks-keyregistry.md)
  - [AshHooks.OutboundDelivery](dsl-ashhooks-outbounddelivery.md)
  - [AshHooks.Subscription](dsl-ashhooks-subscription.md)
  - [AshHooks](dsl-ashhooks.md)

## Modules

- [AshHooks.Endpoint.SecretRef](AshHooks.Endpoint.SecretRef.md): A reference to a consumer-held secret, never the secret itself.
- [AshHooks.Endpoint.Url](AshHooks.Endpoint.Url.md): An outbound webhook destination URL with registration-time validation.
- [AshHooks.Errors](AshHooks.Errors.md): Splode error hierarchy for ash_hooks.
- [AshHooks.Inbound](AshHooks.Inbound.md): Configuration for one inbound webhook declaration.
- [AshHooks.InboundDelivery.LegacyAdoption](AshHooks.InboundDelivery.LegacyAdoption.md): Plans and applies adoption of provider-defined inbound identities.
- [AshHooks.Provider.Mock.Event](AshHooks.Provider.Mock.Event.md): Typed event echoed by `AshHooks.Provider.Mock.handle_event/2`.

- Core
  - [AshHooks](AshHooks.md): Receive, verify, and deduplicate incoming webhooks.
Sign, deliver, retry, and track outgoing webhooks.
  - [AshHooks.DestinationPolicy](AshHooks.DestinationPolicy.md): Lets an application allow or reject a destination URL before the package
checks whether its network address is safe. SSRF means server-side request
forgery: requests that trick a server into reaching unintended addresses.
  - [AshHooks.Info](AshHooks.Info.md): Reads compiled webhook declarations and delivery configuration.

  - [AshHooks.Keyset](AshHooks.Keyset.md): Shared keyset pagination over a stable `(time, id)` ordering: newest
first, opaque cursors, and `{:ok, %{records:, next_cursor:}}` pages.
  - [AshHooks.PrimaryKey](AshHooks.PrimaryKey.md): Complete, metadata-derived primary-key handling for AshHooks ledgers.
  - [AshHooks.Ssrf](AshHooks.Ssrf.md): Destination validation for outbound webhooks.
  - [AshHooks.Telemetry](AshHooks.Telemetry.md): Lifecycle events for ingress, queue admission, outbound delivery, and key disposal.
  - [AshHooks.Tenancy](AshHooks.Tenancy.md): Validates an operation's resource modules against a tenant.

- Inbound
  - [AshHooks.BodyReader](AshHooks.BodyReader.md): Endpoint `body_reader` that caches the raw, pre-parser request bytes for
signature verification.
  - [AshHooks.Inbound.ResolvedSource](AshHooks.Inbound.ResolvedSource.md): One resolved inbound declaration, shared by the HTTP entry point and ingress.
  - [AshHooks.InboundDelivery](AshHooks.InboundDelivery.md): Turns the consumer's resource into the inbound webhook ledger, the
durable deduplication record used by `AshHooks.Ingress`.
  - [AshHooks.InboundDelivery.Payload](AshHooks.InboundDelivery.Payload.md): A decoded inbound webhook body, stored as a JSON object or array.
  - [AshHooks.InboundSource](AshHooks.InboundSource.md): A host-owned resource for inbound webhook keys, provider selection and pause.
  - [AshHooks.Ingress](AshHooks.Ingress.md): The inbound pipeline driver: verify → ingest → claim → handle → mark,
over a ledger resource carrying the `AshHooks.InboundDelivery` extension.
  - [AshHooks.Plug](AshHooks.Plug.md): Optional Plug adapter for the synchronous inbound webhook pipeline.
  - [AshHooks.Provider.DeliveryContext](AshHooks.Provider.DeliveryContext.md): Durable context for provider callbacks, with and without a source resource.

- Outbound
  - [AshHooks.Catalog](AshHooks.Catalog.md): The event catalog read surface: the `outbound` DSL's declared metadata
(each event type's description, payload schema, and version), read back
for event pickers, doc generation, and payload-version negotiation.
  - [AshHooks.Delivery](AshHooks.Delivery.md): Drives one durable outbound delivery through signing, HTTP, and result
persistence. It uses your resource modules and configured HTTP adapter.
`AshHooks.Worker` adds an Oban trigger; this driver also works without Oban.
  - [AshHooks.Dispatcher](AshHooks.Dispatcher.md): Creates one durable delivery for each matching enabled endpoint, then calls
the configured queue callback. A failure for one endpoint does not stop
the others.
  - [AshHooks.Endpoint](AshHooks.Endpoint.md): Configures an Ash resource as an outbound webhook destination, including
its enable/disable state and references to signing secrets.
  - [AshHooks.EndpointHealth](AshHooks.EndpointHealth.md): Computes endpoint health from attempt history and applies an optional
sustained-failure disable policy.
  - [AshHooks.Event](AshHooks.Event.md): An outbound event: its identity, type, exact payload bytes, and optional context.
  - [AshHooks.Outbound](AshHooks.Outbound.md): Configuration for one outbound declaration in the `AshHooks` DSL.
  - [AshHooks.OutboundAttempt](AshHooks.OutboundAttempt.md): Turns the consumer's resource into the outbound attempt history: one
durable row per delivery attempt, written by the delivery runtime beside
its fenced result transitions.
  - [AshHooks.OutboundBinding](AshHooks.OutboundBinding.md): Builds the versioned, opaque identifiers stored in outbound delivery rows.
  - [AshHooks.OutboundDelivery](AshHooks.OutboundDelivery.md): 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.
  - [AshHooks.OutboundEvent](AshHooks.OutboundEvent.md): Turns the consumer's resource into the outbound EVENT log: exactly one
row per dispatched event (its id, type, declared payload version, time,
and exact payload bytes), recorded whether or not any endpoint was
enabled (or existed), with its own retention.
  - [AshHooks.Subscription](AshHooks.Subscription.md): Turns the consumer's resource into the outbound Subscription, specifying which
events go to which endpoint, and with which signature envelope.
  - [AshHooks.Worker](AshHooks.Worker.md): 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.

- Signing
  - [AshHooks.Custody](AshHooks.Custody.md): Custody of opaque webhook keys. Secret bytes never return to ash_hooks
after `c:store/4`.
  - [AshHooks.Custody.Conformance](AshHooks.Custody.Conformance.md): An ExUnit case template for implementations of `AshHooks.Custody`.
  - [AshHooks.Custody.Key](AshHooks.Custody.Key.md): An opaque custody key, identified by custodian, reference, canonical tenant,
and the kind fixed when it was stored. Contains no secret material.
Sender public verification material uses `AshHooks.Custody.PublicKey`.

  - [AshHooks.Custody.PublicKey](AshHooks.Custody.PublicKey.md): A pinned sender public key with its host-selected asymmetric algorithm.
  - [AshHooks.KeyRegistry](AshHooks.KeyRegistry.md): Tracks opaque webhook keys that must be destroyed, using a host Ash resource.
  - [AshHooks.Legacy](AshHooks.Legacy.md): The legacy HMAC webhook envelope for receivers using the `:legacy` or
`:dual` signing modes.
  - [AshHooks.Signing](AshHooks.Signing.md): Standard Webhooks signing and verification for `v1` (HMAC-SHA256) and
`v1a` (ed25519), over `msg_id.timestamp.payload`.

- Inbound verification
  - [AshHooks.Provider](AshHooks.Provider.md): Behavior for inbound webhook providers.
  - [AshHooks.Provider.Conformance](AshHooks.Provider.Conformance.md): An ExUnit case template for a provider's hand-written `decode_payload/2`.
  - [AshHooks.Provider.Event](AshHooks.Provider.Event.md): A verified webhook returned by a configured provider's default handler.
  - [AshHooks.Provider.Hmac](AshHooks.Provider.Hmac.md): A host-configured HMAC verifier for an emitter whose wire contract you own.
  - [AshHooks.Provider.Mock](AshHooks.Provider.Mock.md): Reference provider for tests and examples: HMAC-SHA256 over the raw body via
the default implementation, event type from `payload["type"]`, and an
echoing typed event.
  - [AshHooks.Provider.Scheme](AshHooks.Provider.Scheme.md): A caller-configured webhook verification contract.
  - [AshHooks.Provider.Signature](AshHooks.Provider.Signature.md): Stateless webhook signature verification with caller-pinned keys and algorithms.

- HTTP adapters
  - [AshHooks.Http](AshHooks.Http.md): HTTP adapter contract for outbound delivery.
  - [AshHooks.Http.Bounded](AshHooks.Http.Bounded.md): The default `AshHooks.Http` adapter: HTTP/1.1 over `:gen_tcp` and `:ssl`,
with bounded response collection and one operation deadline.
  - [AshHooks.Http.CertSan](AshHooks.Http.CertSan.md): Checks that an HTTPS certificate names the destination's literal IP address
in an IP subject alternative name. Certificate-chain validation alone does
not establish that match.

  - [AshHooks.Http.Httpc](AshHooks.Http.Httpc.md): An `AshHooks.Http` adapter built on OTP's `:httpc`.
  - [AshHooks.Transport](AshHooks.Transport.md): Use another transport for an endpoint while retaining signing, retry handling,
attempt history, and telemetry. A transport implements the same `request/5`
contract as an HTTP adapter.

- Exceptions
  - [AshHooks.Errors.Invalid](AshHooks.Errors.Invalid.md): The invalid error class: the webhook input or its verification failed.
  - [AshHooks.Errors.Invalid.InvalidSignature](AshHooks.Errors.Invalid.InvalidSignature.md): An inbound webhook's signature did not verify under the provider's scheme.
  - [AshHooks.Errors.Invalid.KeyKindMismatch](AshHooks.Errors.Invalid.KeyKindMismatch.md): A custody key or pinned public key has a kind that cannot perform the requested operation.
This is a final configuration fault. Telemetry reason: `:key_kind_mismatch`.

  - [AshHooks.Errors.Invalid.MalformedPayload](AshHooks.Errors.Invalid.MalformedPayload.md): The webhook payload does not have the shape the provider expects.
  - [AshHooks.Errors.Invalid.NoWebhookSecret](AshHooks.Errors.Invalid.NoWebhookSecret.md): The signing secret for an inbound webhook's provider is unconfigured or
unavailable. The caller verifies nothing and does not run the handler.

  - [AshHooks.Errors.Invalid.StaleTimestamp](AshHooks.Errors.Invalid.StaleTimestamp.md): The timestamp carried by a windowed provider's signature falls outside the
allowed replay window, or a JWS expiration or not-before claim rejects
the current time.

  - [AshHooks.Errors.Invalid.UnknownEventType](AshHooks.Errors.Invalid.UnknownEventType.md): The payload's event type is not one the provider knows.
  - [AshHooks.Errors.Invalid.UnknownKey](AshHooks.Errors.Invalid.UnknownKey.md): A custody key is absent or belongs to another tenant.
A displaced reference is refreshed once from its owner. A reference still
admitted by that owner is a final configuration fault. Telemetry reason: `:unknown_key`.

  - [AshHooks.Errors.Invalid.UnknownSource](AshHooks.Errors.Invalid.UnknownSource.md): An inbound source could not be resolved. Telemetry reason: `:unknown_source`.
  - [AshHooks.Errors.Unknown](AshHooks.Errors.Unknown.md): The unknown error class: unrecognized failures inside ash_hooks.
  - [AshHooks.Errors.Unknown.KeyUnavailable](AshHooks.Errors.Unknown.KeyUnavailable.md): Custody could not answer a key operation. This failure is retryable.
Telemetry reason: `:key_unavailable`. Contains no backend error details.

  - [AshHooks.Errors.Unknown.UnknownError](AshHooks.Errors.Unknown.UnknownError.md): An error ash_hooks did not recognize.

## Mix Tasks

- [mix ash_hooks.install](Mix.Tasks.AshHooks.Install.md): Installs ash_hooks into a host application