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

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:
- `Codat.Webhooks.Plug` — drop-in Plug for Phoenix/Plug apps
- `Codat.Webhooks.Verifier` — standalone signature verification
- `Codat.Webhooks.Handler` — behaviour for typed event handling

## 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)

# `create`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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: ["*"]
    })

---

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