Unit.API.Webhooks (Unit v1.0.0)

API module for Unit Webhook subscriptions.

Delivery modes

AtMostOnce — fired immediately, no retry on failure (default)
AtLeastOnce — batched (up to 64 event IDs per POST), retried on timeout or non-2xx response. Your handler must be idempotent.

Verification

Unit sends a token header with each webhook payload so you can verify the request originated from Unit. Store this token securely and compare it in your handler.

Example

{:ok, webhook} = Unit.API.Webhooks.create(%{
  label: "production-events",
  url: "https://yourapp.com/webhooks/unit",
  token: "your-secret-verification-token",
  content_type: "Json",
  delivery_mode: "AtLeastOnce"
})

Summary

Functions

create(params, opts \\ [])

Create a webhook subscription.

delete(id, opts \\ [])

Delete a webhook subscription.

disable(id, opts \\ [])

Disable a webhook (stops delivery without deleting).

enable(id, opts \\ [])

Enable a previously disabled webhook.

get(id, opts \\ [])

Get a webhook by ID.

list(opts \\ [])

List all webhook subscriptions.

update(id, params, opts \\ [])

Update a webhook subscription.

Functions

create(params, opts \\ [])

@spec create(
  map(),
  keyword()
) :: {:ok, Unit.Resource.Webhook.t()} | {:error, term()}

Create a webhook subscription.

Required params

:label — human-readable name
:url — HTTPS endpoint to receive events
:token — secret for verifying webhook origin

Optional params

:content_type — "Json" (default) or "JsonAPI"
:delivery_mode — "AtMostOnce" (default) or "AtLeastOnce"
:include_resources — boolean; include full resource in payload
:subscribed_events — list of event type strings to filter

delete(id, opts \\ [])

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

Delete a webhook subscription.

disable(id, opts \\ [])

@spec disable(
  String.t(),
  keyword()
) :: {:ok, Unit.Resource.Webhook.t()} | {:error, term()}

Disable a webhook (stops delivery without deleting).

enable(id, opts \\ [])

@spec enable(
  String.t(),
  keyword()
) :: {:ok, Unit.Resource.Webhook.t()} | {:error, term()}

Enable a previously disabled webhook.

get(id, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, Unit.Resource.Webhook.t()} | {:error, term()}

Get a webhook by ID.

list(opts \\ [])

@spec list(keyword()) :: {:ok, [Unit.Resource.Webhook.t()], map()} | {:error, term()}

List all webhook subscriptions.

update(id, params, opts \\ [])

@spec update(String.t(), map(), keyword()) ::
  {:ok, Unit.Resource.Webhook.t()} | {:error, term()}

Update a webhook subscription.

Updatable params

:label, :url, :token, :content_type
:delivery_mode, :include_resources, :subscribed_events