Guidance for maintainers and coding assistants working in applications that use AshHooks 3.3.0.
Build events from exact bytes
- Construct outbound events with
AshHooks.Event.new/1. Pass the exact binary that will be signed and sent; do not pass a map and re-encode it later. - Derive the event ID from the logical event's stable identity whenever the producer can run again. Include a revision or change ID when one source record emits several events. Reusing the event ID lets the ledger and receiver deduplicate repeated delivery.
- Do not construct
%AshHooks.Event{}directly. Dispatch revalidates raw structs, but the constructor gives the caller the validation error before any row is written. - Event IDs cannot contain dots, spaces, invalid UTF-8, or control characters because the
ID is also serialized as the
webhook-idheader.
Receive webhooks through the ledger
- Add
AshHooksandAshHooks.InboundDeliveryto the inbound ledger, setprovideron declarations using declaration-based keys, orsource_recordto select the provider from a source resource's allowlist. Forward routes toAshHooks.Plug. Setresource:and exactly one ofsource:orresolve: {module, function, args}.AshHooks.Ingress.ingest/4remains the lower-level path for custom transports. Signature verification is over the exact raw bytes. There is no name-to-module convention and there are no built-in vendor verifiers. - Configure
body_reader: {AshHooks.BodyReader, :read_body, []}on any precedingPlug.Parsers, or have your own endpoint reader callAshHooks.BodyReader.put_raw_body(conn, complete_bytes)before parsing. Supply the whole body exactly as sent, never partial or re-encoded bytes; the plug retrieves it throughAshHooks.BodyReader.raw_body/1without a second read. Direct ingress callers also useAshHooks.BodyReader.raw_body(conn). Without a parser the plug reads the body itself. Never reconstruct signed bytes from parsed params. Configure parser body limits separately from the plug'slength:,read_length:andread_timeout:for direct reads. - Use
resolve:to look up a stored endpoint from the request path and return{:ok, %{source: source, tenant: tenant, scope: scope, connection: connection}}. Onlysourceis required in that map; multitenant ledgers requiretenant, and scoped identities require their scope slots. Do not trust a path's tenant directly. Return{:error, :not_found}for 404 or{:error, :unavailable}for 503; neither writes. - Set
request_uri:to a configured public base URL or an MFA returning the full URI when the sender signs the URL. The plug never derives it from the internal conn authority.methods:defaults to["POST"]; other methods receive 405 withallow. - A provider written directly against
AshHooks.Providerreads onlyctx.signature(itssignature_source/0is:headerby default). Name its header with the plug'ssignature_header:option, or return:signature_headerfrom the resolver to set it per source. A missing or repeated header is refused as unsigned with 400. Configured providers (verify: [...]) read their own headers and need neither. - Provider
handshake/1may return{:respond, status, headers, body}before method and verification checks, or:deliver. It receives method, decoded query params, request headers and raw bytes. No delivery is written for a handshake response. Signature verification has not run yet: authenticate any challenge exactly as the sender's protocol requires before answering it. - Provider
response/1overrides the plug'srespond:MFA;:defaultfalls through to the host policy, thenAshHooks.Plug.default_response/2(outcome and validated plug options). Both policies receive the exact ingest outcome and never override a plug refusal. Defaults acknowledge terminal rows with 200, retry other ledger outcomes with 500, reject typed signature, timestamp and malformed-payload errors with 400, return 404 forUnknownSource, 500 forUnknownKeyorKeyKindMismatch, and 503 for other ingest failures. - Set
retry_after:to a positive number of seconds (default 60) for the requiredretry-afterheader on default-mapping and resolver 503s. Provider and host ingest-response policies own their 503 headers. - Use
refuse: {module, function, args}to shape refusal headers and bodies. It receives:not_found,:unavailable,:method_not_allowed,:too_large, or:body_consumedand returns{headers, body}or:default. It cannot change the status; requiredallowandretry-afterheaders win on a name conflict. - Describe a sender with
use AshHooks.Provider, verify: [...](options inAshHooks.Provider.Scheme). Copy the scheme from the sender's own documentation: algorithm, signature location, encoding, secret encoding, signed input, and timestamp. Configured providers read their signature fromctx.headers. The plug supplies the ordered request headers and method. For directIngress.ingest/4calls, passheaders: conn.req_headers(so repeated lines survive),method, and the publicrequest_uriwhen the scheme signs them. - Keep every verification option and key in code or the secret source. Never build options, keys, algorithms, or key URLs from the request. Public-key schemes take the sender's PEM key from the secret source.
- Use a
signed_inputortimestamphost function only where the sender canonicalizes (sorted form fields, decoded URLs, fields from the body, unusual timestamp formats). Asigned_inputfunction returns the binary to verify; atimestampfunction returns{:ok, unix_seconds}. Any other result fails verification. - When configuration cannot express a scheme, implement
verify_signature/3with the primitives inAshHooks.Provider.Signature. Compare in constant time and return an error tuple for every malformed input; never raise. - A configured provider classifies every request as
:webhook. Overrideparse_event_type/1with an explicit table of the sender's event names (neverString.to_atom/1), and implement application effects and their idempotency inhandle_event/2. - Include every sender scope needed for uniqueness in
scope_identity, and create the generated unique index in the database. The ledger is the deduplication boundary; do not add a separate seen-events table. - An explicit
event_idextractor takes precedence. Invalid extractor results use the raw-body digest. Without an extractor, ingress usesevent_identity/2when exported, thenevent_identity/1; an invalid provider identity fails ingestion.
Dispatch and drive outbound deliveries
- Add
AshHooksto the emitting resource, declareoutbound, and useAshHooks.dispatch/4for fanout. It creates one durable delivery obligation per matching enabled endpoint. use AshHooks.Workeris the supported Oban integration. Pass itsenqueue/2callback to dispatch so each row receives a durable, uniquely identified trigger.AshHooks.Delivery.run/2is also a supported execution path. It drives an existing delivery row directly for queue-free hosts, custom schedulers, and one-row diagnostics. It does not create the row: dispatch first, then callrun/2with the delivery identity and the delivery and endpoint resources, retry limits, backoff limits, and a secret resolver for any byte slots. Custody slots use the endpoint's custodian. Honor{:snooze, seconds}by scheduling the row again after that delay.- A direct runner must impose the same outer scheduling discipline as the worker. Keep the attempt deadline finite and allow the result-write finalization window to complete.
- The row owns retries, attempt counts, send leases, and terminal state. Oban or a custom scheduler is a trigger only; do not add a second retry policy around the row.
- Delivery is at least once across a crash during transport. Receivers must deduplicate
the stable
webhook-id. retryable_statusesoptionally replaces the HTTP retry set. 2xx, redirects, and 410 keep their package-owned rules. Hostdelivery_headerscallbacks receive the delivery, endpoint, and tenant; they cannot override signature or framing headers.- Optional certificate pins require HTTPS and
AshHooks.Http.Bounded; pin mismatch fails before sending and is non-retryable. Resolve per-endpoint pins from current host configuration, never from process-local state another node would need.
Preserve durable ownership and recovery
- Do not edit
dispatch_source,dispatch_route, attempt tokens, enqueue tokens, leases, or endpoint snapshots. Dispatch, direct execution, workers, and reconciliation use these fields to reject the wrong declaration, route, or stale owner. - Run
AshHooks.reconcile_pending/3periodically for every outbound declaration and tenant that uses queued delivery. It recovers stale pending rows, enqueue failures, due retries, expired sends, and interrupted endpoint disables. Future retries and live leases remain untouched. - Keep the reconciliation cutoff beyond normal enqueue latency. The default is five minutes.
- Named worker callbacks carry a stable route automatically. An anonymous enqueue
callback that must survive reconciliation needs a stable
enqueue_key. An unkeyed anonymous callback cannot be reconstructed and is reported as:unresolved_route. - Custom enqueue callbacks must be idempotent. The enqueue effect may succeed before a claimant crashes and releases its lease.
- Event-log replay takes
declaration: {Emitter, :event_name}and the same tenant as dispatch. Enableresend_tracking :onto store the requester and request time. Enqueue receives the created delivery and its event. Dry runs write nothing. - Health sweeps wait
warning_interval_seconds(default 60) from the stored warning time before disabling. Counts and telemetry reflect successful writes. - When pruning with
attempts:, both resources must support transactions. A history deletion error rolls back the batch and is returned; for SQLite, enablewrite_transactions?/0on the repo. - A 410 response first records
:disable_pendingwith an endpoint snapshot. Recovery may complete that disable only if the endpoint still matches the snapshot; an old response cannot disable replacement configuration.
Treat identity upgrades as data migrations
- When adopting a provider-defined identity for rows created with the former raw-body
digest, first call
AshHooks.Ingress.plan_legacy_identity_adoption/3and review its unresolved rows, conflicts, representative choices, and before/after keys. - Quiesce ingress and reapers before calling
AshHooks.Ingress.adopt_legacy_identity/3withquiesced?: true. Use the same scope, tenant, and canonical-ID overrides that were reviewed in the plan. - Adoption keeps one representative for each canonical identity. Sibling audit rows stay
stored with their original payload and digest and become terminal
:superseded; they are never reaped into handler execution. - Never rewrite provider identities or mark rows superseded with ad hoc updates.
Keep resource references and tenancy consistent
- Endpoint and subscription resources each need one UUID-storage-compatible primary key;
the attribute may have any name and may use
:uuid_v7. The DSL rejects composite or non-UUID keys where scalar delivery references cannot represent them. - Delivery and inbound ledgers may use consumer-defined or composite primary keys. Use
the package's primary-key helpers and full key maps rather than assuming a field named
id. - In a multitenant application, use the same attribute-tenancy contract on every resource
touched by an operation, including optional history and event-log resources, and
pass the tenant to every entry point.
AshHooks.Tenancy.resolve/2checks only its supplied modules; entry points include every resource they read or write. Global tenancy is rejected. Missing or mismatched tenancy fails before data access. - Queue arguments serialize the row tenant and full delivery key so a restart can recover the same scope. Do not replace them with ambient process context.
Keep secrets, responses, and retention bounded
- Inbound secret DSL options take resolver sources, not literal secret bytes: use
{module, function, args},{:app_env, path}, a zero-arity function, or a tenant-aware one-arity function. Persist only secret references. Custody keys sign or verify through their custodian without returning secret material. - The default HTTP adapter validates destinations at send time, pins the validated address, never follows redirects, rejects unsafe headers, and applies one finite deadline across DNS, connect, send, and reads. Keep these guarantees when supplying a custom adapter.
- Response snippets store no body bytes by default. Enable
snippet_capture: trueonly for an explicit diagnostic run. A custom snippet redactor receives the raw captured bytes and must return a binary ornil; a crash or invalid return falls back to the package's sanitized summary. - Use
AshHooks.Ingress.prune/2andAshHooks.Delivery.prune/2to prune supported terminal states. Apply a separate application retention policy to tracked:failed_verificationrows. Only terminal rows are deleted. Inbound:supersededrows are terminal and remain available for audit until the configured retention pass removes them. - The package injects no read policy. Define narrow consumer actions and Ash policies for
ledger, endpoint, and subscription access. Avoid broad
acceptlists on internal state fields.
Common mistakes
- Baking
validate_destination: falseor anhttp_optstimeout:at or above:attempt_timeoutinto a worker module (the macro refuses both; the bypass is the:test-only destination-validation bypass). - Decoding JSON before capturing the raw request body used by the provider signature.
- Generating a new event ID each time the same source record is dispatched.
- Calling
Delivery.run/2without handling{:snooze, seconds}. - Running queued delivery without scheduling
reconcile_pending/3. - Using an anonymous enqueue callback without a stable
enqueue_keywhen recovery is required. - Leaving the generated
:webhookclassification in place when handlers need the sender's event types. - Passing only
ctx.signatureto a configured provider: it reads its signature fromctx.headers. - Reading or updating a row through an assumed
.idinstead of its declared primary key. - Registering a telemetry prefix instead of the complete event name expected by
:telemetry.attach_many/4.