Codat.Platform.Webhooks (codat v1.0.0)

Copy Markdown View Source

Manage webhook consumers via the Codat Platform API.

Webhook consumers are HTTPS endpoints that Codat POSTs to when events occur. This module wraps the Platform API for creating and managing them programmatically.

For receiving and verifying webhooks in your Elixir app, see:

Example

# Create a webhook consumer
{:ok, consumer} = Codat.Platform.Webhooks.create(client, %{
  name: "Production Events",
  url: "https://myapp.com/webhooks/codat",
  eventTypes: ["company.dataConnectionStatusChanged", "invoices.write.successful"]
})

# List all configured consumers
{:ok, page} = Codat.Platform.Webhooks.list(client)

Summary

Functions

create(client_or_body, body_or_opts \\ [])

Creates a new webhook consumer endpoint.

delete(client_or_id, id_or_opts \\ [])

Deletes a webhook consumer.

disable(client_or_id, id_or_opts \\ [])

Disables a webhook consumer so it no longer receives events.

enable(client_or_id, id_or_opts \\ [])

Enables a previously disabled webhook consumer.

get(client_or_id, id_or_opts \\ [])

Fetches a webhook consumer by ID.

list(client_or_opts \\ [], opts \\ [])

Lists all webhook consumers.

messages(client_or_id, id_or_opts \\ [], opts \\ [])

Returns the delivery log for a specific webhook consumer.

update(client_or_id, id_or_body, body_or_opts \\ [])

Updates an existing webhook consumer.

Functions

create(client_or_body, body_or_opts \\ [])

@spec create(Codat.Client.t() | map(), map() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Creates a new webhook consumer endpoint.

Required Fields

  • url — HTTPS endpoint to POST events to (must respond with 2xx within 15s)

Optional Fields

  • name — human-readable label
  • eventTypes — list of event type strings to subscribe to. Pass ["*"] to receive all events. Defaults to all events if omitted.
  • companyId — scope to a single company
  • type — "Portal" or "API" (informational)

Example

{:ok, consumer} = Codat.Platform.Webhooks.create(client, %{
  name: "Invoice Events",
  url: "https://myapp.com/webhooks/codat",
  eventTypes: [
    "invoices.write.successful",
    "invoices.write.unsuccessful"
  ]
})

delete(client_or_id, id_or_opts \\ [])

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

Deletes a webhook consumer.

Example

{:ok, nil} = Codat.Platform.Webhooks.delete(client, "webhook-id")

disable(client_or_id, id_or_opts \\ [])

@spec disable(Codat.Client.t() | String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Disables a webhook consumer so it no longer receives events.

Example

{:ok, consumer} = Codat.Platform.Webhooks.disable(client, "webhook-id")
consumer["status"]  # => "Inactive"

enable(client_or_id, id_or_opts \\ [])

@spec enable(Codat.Client.t() | String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Enables a previously disabled webhook consumer.

Example

{:ok, consumer} = Codat.Platform.Webhooks.enable(client, "webhook-id")
consumer["status"]  # => "Active"

get(client_or_id, id_or_opts \\ [])

@spec get(Codat.Client.t() | String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Fetches a webhook consumer by ID.

Example

{:ok, consumer} = Codat.Platform.Webhooks.get(client, "webhook-id")
consumer["url"]         # => "https://myapp.com/webhooks/codat"
consumer["status"]      # => "Active"

list(client_or_opts \\ [], opts \\ [])

@spec list(
  Codat.Client.t() | keyword(),
  keyword()
) :: {:ok, Codat.Pagination.t()} | {:error, Codat.Error.t()}

Lists all webhook consumers.

Example

{:ok, page} = Codat.Platform.Webhooks.list(client)
consumers = page.results

messages(client_or_id, id_or_opts \\ [], opts \\ [])

@spec messages(Codat.Client.t() | String.t(), String.t() | keyword(), keyword()) ::
  {:ok, Codat.Pagination.t()} | {:error, Codat.Error.t()}

Returns the delivery log for a specific webhook consumer.

Example

{:ok, page} = Codat.Platform.Webhooks.messages(client, "webhook-id")
msgs = page.results

update(client_or_id, id_or_body, body_or_opts \\ [])

@spec update(Codat.Client.t() | String.t(), String.t() | map(), map() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Updates an existing webhook consumer.

Example

{:ok, consumer} = Codat.Platform.Webhooks.update(client, "webhook-id", %{
  eventTypes: ["*"]
})