This walkthrough receives a signed order event, records an idempotent business effect in PostgreSQL, and creates an outbound delivery. It uses an existing Ash application with PostgreSQL. For a complete SQLite walkthrough and real outbound request, run the Livebook.
Requires Elixir ~> 1.20, Erlang/OTP 28 or 29, and Ash
>= 3.37.2 and < 4.0.0-0. Inbound works without Oban. Add these entries to your
application's dependency list; the optional Oban entry supports the generated worker.
The dependency-list fragment is tested as part of a Mix project module.
def deps do
[
{:ash_hooks, "~> 3.3"},
{:ash_postgres, "~> 2.0"},
# Optional: required for the generated Oban worker.
{:oban, "~> 2.24"}
]
endEvery supported Ash version requires string-length configuration before resources
compile. Put this fragment in config/config.exs, after import Config.
config :ash, default_string_length_count: :codepointsCreate the tables
Run this fragment inside the change/0 function of an Ecto migration. It is
executed against real PostgreSQL as part of this complete application example.
The unique indexes preserve one inbound identity and one delivery per endpoint/event.
The scope column is required on every ingest. Optional response-capture columns
are included below but unused until the endpoint enables that feature.
# inbound ledger: payload is the decoded body (a :map / JSONB column);
# payload_digest binds it to the signed raw bytes
create table(:webhook_ledgers, primary_key: false) do
add :id, :uuid, primary_key: true
add :provider, :text, null: false
add :external_event_id, :text, null: false
add :external_event_type, :text
add :payload, :map, null: false
add :payload_digest, :text, null: false
add :status, :text, null: false, default: "received"
add :fencing_token, :integer, null: false, default: 0
add :lease_expires_at, :utc_datetime_usec
add :error_class, :text
add :attempts, :integer, null: false, default: 0
# one column per scope_identity slot:
add :account_id, :text, null: false
timestamps(type: :utc_datetime_usec)
end
create unique_index(:webhook_ledgers, [:provider, :external_event_id, :account_id])
# outbound ledger: payload here is the exact bytes to sign
create table(:outbound_deliveries, primary_key: false) do
add :id, :uuid, primary_key: true
add :event_uuid, :text, null: false
add :event_type, :text, null: false
add :payload, :binary, null: false
add :endpoint_id, :uuid, null: false
add :subscription_id, :uuid
add :signing_mode, :text
add :status, :text, null: false, default: "pending"
add :attempts, :integer, null: false, default: 0
add :response_status, :integer
add :response_snippet, :text
add :last_error, :text
add :next_attempt_at, :utc_datetime_usec
add :dispatch_source, :text, null: false, default: "v1:direct:unbound"
add :dispatch_route, :text, null: false, default: "v1:route:unbound"
add :attempt_token, :uuid
add :send_lease_expires_at, :utc_datetime_usec
add :enqueue_token, :uuid
add :enqueue_lease_expires_at, :utc_datetime_usec
add :endpoint_snapshot, :map
timestamps(type: :utc_datetime_usec)
end
create unique_index(:outbound_deliveries, [:endpoint_id, :event_uuid])
create table(:webhook_endpoints, primary_key: false) do
add :id, :uuid, primary_key: true
add :url, :text, null: false
add :status, :text, null: false, default: "enabled"
add :secret_ref, :text, null: false
add :previous_secret_ref, :text
add :legacy_secret_ref, :text
add :legacy_previous_secret_ref, :text
# only when the endpoint declares `response_capture_attributes :on`:
add :response_capture, :boolean, null: false, default: false
add :response_capture_max_bytes, :integer, null: false, default: 2048
add :response_capture_retention_seconds, :integer, null: false, default: 2_592_000
add :response_header_allowlist, {:array, :text}, null: false, default: []
end
# the attempt history (optional; see "Other optional features"):
# one row per delivery attempt, written by the runtime
create table(:outbound_attempts, primary_key: false) do
add :id, :uuid, primary_key: true
add :delivery_pk, :map, null: false
add :endpoint_id, :uuid, null: false
add :event_uuid, :text, null: false
add :event_type, :text, null: false
add :attempt, :integer, null: false
add :outcome, :text, null: false
add :reason, :text
add :response_status, :integer
add :response_snippet, :text
add :response_headers, :map
add :latency_ms, :integer
add :signing_key_ref, :text
add :test, :boolean, null: false, default: false
add :attempted_at, :utc_datetime_usec, null: false
end
create unique_index(:outbound_attempts, [:delivery_pk, :attempt])
create table(:webhook_subscriptions, primary_key: false) do
add :id, :uuid, primary_key: true
add :event_types, {:array, :text}, null: false
add :endpoint_id, :uuid, null: false
add :signing_mode, :text
end
create table(:orders, primary_key: false) do
add :id, :uuid, primary_key: true
add :paid, :boolean, null: false, default: false
endSee Other optional features for attempt-history ownership.
Declare the resources
The following complete example uses the tables above. Put each module in its own
source file in your application. Configure MyApp.Repo with your PostgreSQL
connection and supervise it before making calls. Register MyApp.Domain in your
application's :ash_domains configuration. These resources are called by trusted
application code; add policies before exposing them to actors.
defmodule MyApp.Repo do
use AshPostgres.Repo,
otp_app: :my_app,
warn_on_missing_ash_functions?: false
def min_pg_version, do: %Version{major: 16, minor: 0, patch: 0}
end
defmodule MyApp.Order do
use Ash.Resource,
domain: MyApp.Domain,
data_layer: AshPostgres.DataLayer,
extensions: [AshHooks]
postgres do
table "orders"
repo MyApp.Repo
end
attributes do
uuid_primary_key :id
attribute :paid, :boolean, allow_nil?: false, default: false
end
actions do
defaults [:read, :create, :update]
default_accept [:paid]
end
webhooks do
outbound :order_paid do
subscriptions MyApp.WebhookSubscription
deliveries MyApp.OutboundDelivery
end
end
end
defmodule MyApp.Webhooks.Orders do
use AshHooks.Provider,
verify: [
algorithm: :hmac_sha256,
signature: {:header, "x-orders-signature"},
encoding: :hex
]
@impl true
def parse_event_type(%{"type" => "order.paid"}), do: {:ok, :order_paid}
def parse_event_type(_payload), do: {:error, :unknown_event_type}
@impl true
def handle_event(:order_paid, %{"order_id" => id} = payload) do
# Setting the same paid flag twice has the same business effect as once.
with {:ok, order} <- Ash.get(MyApp.Order, id, authorize?: false),
{:ok, _order} <- Ash.update(order, %{paid: true}, authorize?: false) do
{:ok, %AshHooks.Provider.Event{type: :order_paid, payload: payload}}
else
{:error, reason} -> {:error, :retry, reason}
end
end
def handle_event(_type, _payload), do: {:error, :permanent, :unhandled_event}
end
defmodule MyApp.WebhookLedger do
use Ash.Resource,
domain: MyApp.Domain,
data_layer: AshPostgres.DataLayer,
extensions: [AshHooks, AshHooks.InboundDelivery]
postgres do
table "webhook_ledgers"
repo MyApp.Repo
end
inbound_delivery do
scope_identity [:account_id]
end
attributes do
attribute :account_id, :string, allow_nil?: false
timestamps()
end
actions do
defaults [:read]
end
webhooks do
inbound :orders do
provider MyApp.Webhooks.Orders
secret {:app_env, [:my_app, :orders_webhook_secret]}
event_id &__MODULE__.event_id/1
end
end
def event_id(%{"id" => id}) when is_binary(id), do: {:ok, id}
def event_id(_payload), do: :error
end
defmodule MyApp.WebhookEndpoint do
use Ash.Resource,
domain: MyApp.Domain,
data_layer: AshPostgres.DataLayer,
extensions: [AshHooks.Endpoint]
postgres do
table "webhook_endpoints"
repo MyApp.Repo
end
actions do
defaults [:read, :create, :update]
default_accept :*
end
end
defmodule MyApp.WebhookSubscription do
use Ash.Resource,
domain: MyApp.Domain,
data_layer: AshPostgres.DataLayer,
extensions: [AshHooks.Subscription]
postgres do
table "webhook_subscriptions"
repo MyApp.Repo
end
actions do
defaults [:read, :create]
default_accept :*
end
subscription do
endpoint_resource MyApp.WebhookEndpoint
end
end
defmodule MyApp.OutboundDelivery do
use Ash.Resource,
domain: MyApp.Domain,
data_layer: AshPostgres.DataLayer,
extensions: [AshHooks.OutboundDelivery]
postgres do
table "outbound_deliveries"
repo MyApp.Repo
end
actions do
defaults [:read]
end
attributes do
timestamps()
end
end
defmodule MyApp.OutboundAttempt do
use Ash.Resource,
domain: MyApp.Domain,
data_layer: AshPostgres.DataLayer,
extensions: [AshHooks.OutboundAttempt]
postgres do
table "outbound_attempts"
repo MyApp.Repo
end
actions do
defaults [:read]
end
end
defmodule MyApp.Domain do
use Ash.Domain, otp_app: :my_app
resources do
resource MyApp.Order
resource MyApp.WebhookLedger
resource MyApp.WebhookEndpoint
resource MyApp.WebhookSubscription
resource MyApp.OutboundDelivery
resource MyApp.OutboundAttempt
end
endThis declaration uses an explicit provider. A source_record declaration
selects its provider from the source resource's allowlist. The inbound name is
part of the ledger identity and must
stay stable. The explicit event ID extractor takes precedence; invalid results
use the raw-body digest. Without it, a provider identity callback is used when
implemented, and an invalid provider identity fails ingestion. With neither,
ingress uses the raw-body SHA-256.
Verify and handle an incoming event
The following calls run after the resources and migration above. This example sets an application secret, creates an order, signs exact bytes, and ingests twice. In production, load the secret through your configured secret store. It is never embedded in the compiled webhook declaration. Use unique event IDs for distinct events, and reuse the ID for redelivery.
Application.put_env(:my_app, :orders_webhook_secret, :crypto.strong_rand_bytes(32))
{:ok, order} = Ash.create(MyApp.Order, %{}, authorize?: false)
raw_body = Jason.encode!(%{"type" => "order.paid", "id" => "event-1", "order_id" => order.id})
secret = Application.fetch_env!(:my_app, :orders_webhook_secret)
signature = :crypto.mac(:hmac, :sha256, secret, raw_body) |> Base.encode16(case: :lower)
ctx = %{headers: [{"x-orders-signature", signature}], scope: %{account_id: "account-1"}}
{:ok, :created, %{status: :processed}} =
AshHooks.Ingress.ingest(MyApp.WebhookLedger, :orders, raw_body, ctx)
{:ok, :duplicate, %{status: :processed}} =
AshHooks.Ingress.ingest(MyApp.WebhookLedger, :orders, raw_body, ctx)
{:ok, %{paid: true}} = Ash.get(MyApp.Order, order.id, authorize?: false)The ledger runs handlers at least once. A crash between the business effect and
recording success can repeat the handler. This handler's update is idempotent.
Returned retry and permanent failures are recorded. A handler exception, exit,
or throw is contained and recorded as :failed_retryable with error class
"handler_crashed". The handler can be retried through the stored ledger.
For HTTP receipt, configure AshHooks.BodyReader before parsers consume the bytes,
then mount AshHooks.Plug. The README
contains tested Phoenix mounting fragments. Scoped and multitenant routes need a
resolver for the application's inbound route. It returns the source, scope,
connection, and tenant.
Never trust a path parameter as a module or tenant.
The plug acknowledges terminal rows with 200, returns 500 for pending, claimed,
or retryable outcomes, 400 for typed invalid-signature/stale-timestamp/malformed
errors, 404 for UnknownSource, 500 for UnknownKey or KeyKindMismatch,
and 503 for other ingestion errors. Default 503s include retry-after.
Permanent failures need an operator-visible record because redelivery cannot
repair a terminal row. See AshHooks.Plug for custom response and refusal callbacks.
Create an outbound delivery
Use the existing public receiver you control: set PUBLIC_WEBHOOK_TEST_URL to
its public HTTPS webhook URL. This example only creates the durable row. It does
not send until a worker or the direct runner drives it. Endpoint registration
rejects private, loopback, and special-purpose literal IP addresses. DNS names
are resolved and checked at send time.
The notebook shows an explicit local destination policy for its existing receiver.
{:ok, endpoint} =
Ash.create(
MyApp.WebhookEndpoint,
%{
url: System.fetch_env!("PUBLIC_WEBHOOK_TEST_URL"),
secret_ref: "outbound-main"
},
authorize?: false
)
{:ok, _subscription} =
Ash.create(
MyApp.WebhookSubscription,
%{
endpoint_id: endpoint.id,
event_types: ["order_paid"]
},
authorize?: false
)
{:ok, event} =
AshHooks.Event.new(
type: :order_paid,
payload: Jason.encode!(%{order_id: order.id}),
id: "msg_order-" <> order.id
)
{:ok, [%{status: :deferred}]} = AshHooks.dispatch(MyApp.Order, :order_paid, event)
{:ok, %{records: [delivery]}} =
AshHooks.Delivery.list(MyApp.OutboundDelivery, endpoint_id: endpoint.id, status: [:pending])For queued delivery, add an Oban migration, supervise an Oban instance with a
:webhooks queue, and define this worker. Set oban: to the supervised instance
name; omit it for the default Oban instance. The worker is compiled with this
application example; the notebook executes direct delivery to its real receiver.
defmodule MyApp.Secrets do
def webhook_secret("outbound-main") do
case System.fetch_env("OUTBOUND_WEBHOOK_SECRET") do
{:ok, secret} -> {:ok, secret}
:error -> {:error, :missing_secret}
end
end
def webhook_secret(_unknown), do: {:error, :unknown_reference}
end
defmodule MyApp.WebhookDeliveryWorker do
use AshHooks.Worker,
deliveries: MyApp.OutboundDelivery,
endpoints: MyApp.WebhookEndpoint,
attempts: MyApp.OutboundAttempt,
secret_resolver: {MyApp.Secrets, :webhook_secret},
queue: :webhooks,
oban: MyApp.Oban
endGenerate a signing secret once with AshHooks.Signing.generate_secret/0, store the
complete value under the endpoint reference, and return it unchanged. Dispatch
with enqueue: {MyApp.WebhookDeliveryWorker, :enqueue} once Oban is running.
Schedule AshHooks.reconcile_pending/3 for every declaration and tenant using the
same callback. It repairs persistence/enqueue gaps, due retries, expired sends,
and pending 410 disables. Delivery remains at least once across the network.
Receivers deduplicate by webhook-id; keep application clocks synchronized.
The worker signs according to Standard Webhooks, succeeds on 2xx responses, retries 408/429/5xx and transport errors, refuses redirects, and permanently fails other client errors. Retry-After is bounded; otherwise retries use exponential backoff with random delay. HTTP 410 records a pending disable obligation before conditionally disabling the matching endpoint configuration. Use telemetry to make failures and endpoint disablement visible to operators.
Other optional features
- Attempt history uses the resource and migration above. Pass
attempts:to the worker or direct runner. History-write failure emits telemetry without undoing the completed result transition. HTTP 410 history includes the real duration and signing-key reference. - Query deliveries and attempts with keyset pagination. Pass each query's own
next_cursorback asafter:; do not share cursors between different queries. A full last page still has a cursor, and a shorter page has nil. - Endpoint opt-in captures bounded, redacted response bodies in attempt history.
Delivery rows contain a summary unless a direct run sets
snippet_capture: true. Retryable rows must be due; terminal rows must first be rearmed withresend/2. payload_attributerenames the delivery's byte column.prune_action :noneprevents injection of:prune; application-defined destroy actions remain. Endpoint mapping uses an application enable switch. Subscription event types can be constrained atoms or strings; application declarations replace generated constraints and defaults.- Test sends, resend, bulk replay, key rolling, catalog metadata, payload versions, subscription filters, an event log, custom transports, inbound queries, pausing, secret rotation, and a destination policy callback are documented at their modules. The README explains their configuration and storage requirements.
Applications own policies, queue and retention schedules, and secret storage.
Inbound pruning excludes tracked rejected-verification rows. Delivery pruning
with attempts: deletes history in the same transaction and returns deletion errors.
Both resources must support transactions; for SQLite, enable write_transactions?/0
on the repo. Optional resources need the same tenant contract
and matching indexes as the core resources.
Observing: telemetry
This example observes the basic delivery lifecycle. See AshHooks.Telemetry for
all optional-feature events. The fragment runs inside this application example.
:telemetry.attach_many(
"my-ash-hooks",
[
[:ash_hooks, :ingress, :verify],
[:ash_hooks, :ingress, :dedup],
[:ash_hooks, :ingress, :claim],
[:ash_hooks, :dispatch, :enqueue_failed],
[:ash_hooks, :delivery, :attempt],
[:ash_hooks, :delivery, :result],
[:ash_hooks, :delivery, :backoff],
[:ash_hooks, :delivery, :dead_letter],
[:ash_hooks, :delivery, :disable]
],
fn event, measurements, metadata, _config ->
require Logger
Logger.debug("#{inspect(event)} #{inspect(measurements)} #{inspect(metadata)}")
end,
nil
)Forward measurements and identifiers to your metrics system. attach_many matches exact names; events omit bodies,
payloads, and signing secrets.
Next steps
Continue with key custody and lifecycle to implement a custodian, issue endpoint keys through a registry, roll and retire both signing slots, migrate byte references, and own inbound keys with source records. It also covers pausable subscriptions and disposal failure recovery. Run these features in the Livebook.
The verification guide covers request-scoped JSON policy and provider delivery context. The tenancy checklist explains canonical tenant handling; the row-security guide adds PostgreSQL transaction binding and policies. Use the upgrade guide when adopting these features on existing tables.
For advanced outbound delivery, follow event recovery, catalogs and filters, and delivery operations.