Syntropy.Webhooks.Registry (syntropy v0.3.0)

Copy Markdown

Registry of webhook endpoints and their recent delivery attempts.

Registrations live in this GenServer's state and, when persistence is enabled, write through to Postgres so they survive gateway restarts. On startup the registry hydrates from the durable store (scoped to this node id, like knowledge items). Writes degrade like events — a failed Postgres write is recorded in persistence health but never blocks the registration. Delivery logs stay in-memory as a bounded ring buffer.

Summary

Types

delivery()
webhook()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

list(server \\ __MODULE__)

List all registered webhooks with their recent deliveries, newest first.

matching(server \\ __MODULE__, event_id)

Active webhooks subscribed to the given runtime event id.

record_delivery(server \\ __MODULE__, id, delivery)

Record one delivery attempt outcome for an endpoint.

register(server \\ __MODULE__, attrs)

Register a webhook endpoint.

remove(server \\ __MODULE__, id)

Remove one webhook registration.

reset(server \\ __MODULE__)

Clear all registrations (test support).

set_active(server \\ __MODULE__, id, active)

Update the active flag of one webhook.

start_link(opts \\ [])

Types

delivery()

@type delivery() :: %{
  event_id: String.t(),
  status: :delivered | :failed,
  http_status: non_neg_integer() | nil,
  attempts: non_neg_integer(),
  error: String.t() | nil,
  delivered_at: DateTime.t()
}

webhook()

@type webhook() :: %{
  id: String.t(),
  url: String.t(),
  events: [String.t()],
  secret: String.t(),
  active: boolean(),
  inserted_at: DateTime.t()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

list(server \\ __MODULE__)

@spec list(GenServer.server()) :: [{webhook(), [delivery()]}]

List all registered webhooks with their recent deliveries, newest first.

matching(server \\ __MODULE__, event_id)

@spec matching(GenServer.server(), String.t()) :: [webhook()]

Active webhooks subscribed to the given runtime event id.

record_delivery(server \\ __MODULE__, id, delivery)

@spec record_delivery(GenServer.server(), String.t(), delivery()) :: :ok

Record one delivery attempt outcome for an endpoint.

register(server \\ __MODULE__, attrs)

@spec register(GenServer.server(), map()) :: {:ok, webhook()} | {:error, [map()]}

Register a webhook endpoint.

attrs must contain a valid http(s) url and a non-empty events list of runtime event ids (or "*" for all). A secret may be supplied so platform-managed secrets stay consistent; otherwise one is generated.

remove(server \\ __MODULE__, id)

@spec remove(GenServer.server(), String.t()) :: :ok | {:error, :not_found}

Remove one webhook registration.

reset(server \\ __MODULE__)

@spec reset(GenServer.server()) :: :ok

Clear all registrations (test support).

set_active(server \\ __MODULE__, id, active)

@spec set_active(GenServer.server(), String.t(), boolean()) ::
  {:ok, webhook()} | {:error, :not_found}

Update the active flag of one webhook.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()