Codat.Webhooks.Handler behaviour (codat v1.0.0)

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

Summary

Types

event_type()

metadata()

payload()

result()

Callbacks

handle_event(event_type, payload, metadata)

on_exception(event_type, payload, t, list)

Types

event_type()

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

metadata()

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

payload()

@type payload() :: map()

result()

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

Callbacks

handle_event(event_type, payload, metadata)

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

on_exception(event_type, payload, t, list)

(optional)

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