# AshHooks v2.0.3 - Table of Contents

> Webhooks for Ash Framework — inbound verification + dedup, outbound signing + delivery

## 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)
  - [Multi-tenant adoption checklist](tenancy-adoption-checklist.md)

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

- DSLs
  - [AshHooks.Endpoint](dsl-ashhooks-endpoint.md)
  - [AshHooks.InboundDelivery](dsl-ashhooks-inbounddelivery.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.ComplyCube.Event](AshHooks.Provider.ComplyCube.Event.md): Typed event echoed by `AshHooks.Provider.ComplyCube.handle_event/2`.
- [AshHooks.Provider.HubSpotV3.Event](AshHooks.Provider.HubSpotV3.Event.md): Typed event echoed by `AshHooks.Provider.HubSpotV3.handle_event/2`.
- [AshHooks.Provider.Mock.Event](AshHooks.Provider.Mock.Event.md): Typed event echoed by `AshHooks.Provider.Mock.handle_event/2`.

- Core
  - [AshHooks](AshHooks.md): Webhooks for Ash Framework — inbound (receive, verify, dedup → domain events)
and outbound (sign, deliver, retry, track).
  - [AshHooks.Info](AshHooks.Info.md): Accessors for a resource's `webhooks` declarations, read via
`Spark.Dsl.Extension` (the ash_age pattern — no generated getter in this
spark version).

  - [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, and outbound delivery.
  - [AshHooks.Tenancy](AshHooks.Tenancy.md): The tenancy contract resolver: every public entry family resolves the
resources it touches BEFORE any data access.

- Inbound
  - [AshHooks.BodyReader](AshHooks.BodyReader.md): Endpoint `body_reader` that caches the raw, pre-parser request bytes for
signature verification.
  - [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.Ingress](AshHooks.Ingress.md): The inbound pipeline driver: verify → ingest → claim → handle → mark,
over a ledger resource carrying the `AshHooks.InboundDelivery` extension.

- Outbound
  - [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): The outbound fanout driver: one event → every matching subscription's
endpoint → a durable per-endpoint delivery row (+ an enqueue handoff),
with per-endpoint isolation — the outbound twin of `AshHooks.Ingress`.
  - [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.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.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.Subscription](AshHooks.Subscription.md): Turns the consumer's resource into the outbound Subscription — which
events go to which endpoint, and with which signature envelope.
  - [AshHooks.Worker](AshHooks.Worker.md): The host-injected Oban worker (ADR-0004): the consuming app defines one
module, and the Oban beam compiles only where Oban exists. This macro
expands `use Oban.Worker` inside the host's compilation, so the package
itself never references a loaded Oban module and compiles Oban-free
(the CI no-optional leg's proof).

- Signing
  - [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`.

- Providers
  - [AshHooks.Provider](AshHooks.Provider.md): Behavior for inbound webhook providers.
  - [AshHooks.Provider.ComplyCube](AshHooks.Provider.ComplyCube.md): Verifies ComplyCube signatures and parses webhook events.
  - [AshHooks.Provider.HubSpotV3](AshHooks.Provider.HubSpotV3.md): Verifies HubSpot v3 webhook signatures and parses event batches.
  - [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.

- 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): iPAddress Subject-Alternative-Name matching for the literal-IP https
floor (ADR-0009's TLS posture): a destination addressed by IP literal
has no hostname for RFC 6125 to check, so the peer certificate must
carry the exact IP in its `iPAddress` SAN — chain validation alone
would let ANY publicly-trusted cert authenticate the peer.
  - [AshHooks.Http.Httpc](AshHooks.Http.Httpc.md): An `AshHooks.Http` adapter built on OTP's `:httpc`.

- 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.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.

  - [AshHooks.Errors.Invalid.UnknownEventType](AshHooks.Errors.Invalid.UnknownEventType.md): The payload's event type is not one the provider knows.
  - [AshHooks.Errors.Unknown](AshHooks.Errors.Unknown.md): The unknown error class — unrecognized failures inside ash_hooks.
  - [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