> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavioapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage webhooks

> Create, list, and delete webhook subscriptions.

Manage your webhook subscriptions to receive real-time notifications when events occur in Mavio.

## Create a webhook

`POST /webhooks`

<ParamField body="url" type="string" required>
  The HTTPS URL where webhook payloads will be sent via POST requests.
</ParamField>

<ParamField body="events" type="string[]" required>
  Array of event types to subscribe to. See [webhook events](/api-reference/webhooks/events) for the full list.
</ParamField>

<ParamField body="secret" type="string">
  Optional signing secret for payload verification. If provided, all payloads will include an `X-Mavio-Signature` header.
</ParamField>

<ParamField body="description" type="string">
  Optional description for this webhook endpoint.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.mavioapp.com/v1/webhooks \
    -H "Authorization: Bearer mvo_live_abc123" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://yourapp.com/webhooks/mavio",
      "events": ["meeting.completed", "transcript.ready", "summary.ready"],
      "secret": "whsec_your_signing_secret",
      "description": "Production event handler"
    }'
  ```

  ```python Python theme={null}
  webhook = client.webhooks.create(
      url="https://yourapp.com/webhooks/mavio",
      events=["meeting.completed", "transcript.ready", "summary.ready"],
      secret="whsec_your_signing_secret"
  )
  ```

  ```javascript Node.js theme={null}
  const webhook = await client.webhooks.create({
    url: 'https://yourapp.com/webhooks/mavio',
    events: ['meeting.completed', 'transcript.ready', 'summary.ready'],
    secret: 'whsec_your_signing_secret',
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "whk_a1b2c3d4e5",
    "url": "https://yourapp.com/webhooks/mavio",
    "events": ["meeting.completed", "transcript.ready", "summary.ready"],
    "description": "Production event handler",
    "active": true,
    "created_at": "2026-04-14T12:00:00Z"
  }
  ```
</ResponseExample>

***

## List webhooks

`GET /webhooks`

Returns all webhook subscriptions for the authenticated account.

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.mavioapp.com/v1/webhooks \
    -H "Authorization: Bearer mvo_live_abc123"
  ```

  ```python Python theme={null}
  webhooks = client.webhooks.list()
  ```

  ```javascript Node.js theme={null}
  const { data } = await client.webhooks.list();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "whk_a1b2c3d4e5",
        "url": "https://yourapp.com/webhooks/mavio",
        "events": ["meeting.completed", "transcript.ready", "summary.ready"],
        "description": "Production event handler",
        "active": true,
        "created_at": "2026-04-14T12:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Delete a webhook

`DELETE /webhooks/{webhook_id}`

Permanently deletes a webhook subscription. Events will no longer be delivered to this endpoint.

<ParamField path="webhook_id" type="string" required>
  The ID of the webhook to delete.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE https://api.mavioapp.com/v1/webhooks/whk_a1b2c3d4e5 \
    -H "Authorization: Bearer mvo_live_abc123"
  ```

  ```python Python theme={null}
  client.webhooks.delete("whk_a1b2c3d4e5")
  ```

  ```javascript Node.js theme={null}
  await client.webhooks.delete('whk_a1b2c3d4e5');
  ```
</RequestExample>

<ResponseExample>
  ```json 204 theme={null}
  ```
</ResponseExample>