Chronicle.WebHooks (cratis_chronicle v1.0.1)

Copy Markdown View Source

Idiomatic API for working with Chronicle webhooks.

Webhooks let Chronicle push observed events to external HTTP endpoints. They can be registered imperatively, or declared as discoverable modules with use Chronicle.WebHooks.Webhook and auto-registered by Chronicle.Client.

Discoverable webhooks

defmodule MyApp.WebHooks.AccountEvents do
  use Chronicle.WebHooks.Webhook,
    target_url: "https://example.com/chronicle/webhooks"

  alias Chronicle.WebHooks.DefinitionBuilder

  @impl true
  def define(builder) do
    builder
    |> DefinitionBuilder.with_event_type(MyApp.Events.AccountOpened)
    |> DefinitionBuilder.with_bearer_token(System.fetch_env!("WEBHOOK_TOKEN"))
  end
end

Imperative registration

:ok =
  Chronicle.WebHooks.register(
    "account-events",
    "https://example.com/chronicle/webhooks",
    fn builder ->
      builder
      |> Chronicle.WebHooks.DefinitionBuilder.with_event_type(MyApp.Events.AccountOpened)
      |> Chronicle.WebHooks.DefinitionBuilder.with_header("x-source", "my-app")
    end
  )

Options

  • :client — the client name (default: Chronicle.Client)
  • :namespace — accepted for consistency with other APIs and ignored here

Summary

Functions

all(opts \\ [])

Gets all registered webhooks for the current event store.

discover(opts \\ [])

Discovers webhook definitions from the configured client or loaded modules.

register(webhook_module, opts \\ [])

Registers a single discoverable webhook module.

register(webhook_id, target_url, configure, opts \\ [])

Registers a webhook imperatively.

register_discovered(opts \\ [])

Registers all discoverable webhooks.

remove(webhook_id, opts \\ [])

Removes a webhook by identifier.

Functions

all(opts \\ [])

@spec all(keyword()) :: {:ok, [Chronicle.WebHooks.Definition.t()]} | {:error, term()}

Gets all registered webhooks for the current event store.

discover(opts \\ [])

@spec discover(keyword()) :: [Chronicle.WebHooks.Definition.t()]

Discovers webhook definitions from the configured client or loaded modules.

register(webhook_module, opts \\ [])

@spec register(
  module(),
  keyword()
) :: :ok | {:error, term()}

Registers a single discoverable webhook module.

register(webhook_id, target_url, configure, opts \\ [])

@spec register(
  String.t(),
  String.t(),
  (Chronicle.WebHooks.DefinitionBuilder.t() ->
     Chronicle.WebHooks.DefinitionBuilder.t()),
  keyword()
) :: :ok | {:error, term()}

Registers a webhook imperatively.

register_discovered(opts \\ [])

@spec register_discovered(keyword()) :: :ok | {:error, term()}

Registers all discoverable webhooks.

remove(webhook_id, opts \\ [])

@spec remove(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Removes a webhook by identifier.