# `Chronicle.WebHooks`
[🔗](https://github.com/Cratis/Chronicle.Elixir/blob/main/lib/chronicle/web_hooks.ex#L4)

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

# `all`

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

Gets all registered webhooks for the current event store.

# `discover`

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

Discovers webhook definitions from the configured client or loaded modules.

# `register`

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

Registers a single discoverable webhook module.

# `register`

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

Registers a webhook imperatively.

# `register_discovered`

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

Registers all discoverable webhooks.

# `remove`

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

Removes a webhook by identifier.

---

*Consult [api-reference.md](api-reference.md) for complete listing*