# `Codat.Webhooks.Handler`
[🔗](https://github.com/iamkanishka/codat.git/blob/v1.0.0/lib/codat/webhooks/handler.ex#L1)

Behaviour for implementing typed Codat webhook event handlers.

## Example

    defmodule MyApp.CodatWebhookHandler do
      use Codat.Webhooks.Handler

      @impl true
      def handle_event("invoices.write.successful", payload, _metadata) do
        MyApp.InvoiceSync.handle_success(payload["companyId"], payload["data"])
        :ok
      end

      @impl true
      def handle_event(_event_type, _payload, _metadata), do: :ok
    end

## Return Values

- `:ok` — processed; Plug responds `200 OK`
- `{:error, reason}` — app error; Plug logs and responds `200 OK`
- `{:retry, reason}` — Plug responds `500` to trigger Codat retry

# `event_type`

```elixir
@type event_type() :: String.t()
```

# `metadata`

```elixir
@type metadata() :: %{
  message_id: String.t(),
  timestamp: integer(),
  attempt_number: non_neg_integer() | nil
}
```

# `payload`

```elixir
@type payload() :: map()
```

# `result`

```elixir
@type result() :: :ok | {:error, term()} | {:retry, term()}
```

# `handle_event`

```elixir
@callback handle_event(event_type(), payload(), metadata()) :: result()
```

# `on_exception`
*optional* 

```elixir
@callback on_exception(event_type(), payload(), Exception.t(), list()) :: :ok
```

---

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