> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fynapse.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fynapse.app/_mcp/server.

# Webhook Configuration

> Learn how to configure webhooks in Fynapse, including managing subscriptions, secrets, and required API permissions.

## Overview

All webhook-related API endpoints require authentication and appropriate permissions.

## Permission Model

To work with webhooks, the following permissions are used:

* `webhook_subscription_read`
* `webhook_subscription_edit`
* `delivery_audit_read`

| Endpoint                                                 | Operations                                 | Required permission         |
| -------------------------------------------------------- | ------------------------------------------ | --------------------------- |
| `/api/v1/event-deliveries/secrets`                       | list / get details                         | `webhook_subscription_read` |
| `/api/v1/event-deliveries/secrets`                       | create, patch, rotate, delete              | `webhook_subscription_edit` |
| `/api/v1/event-deliveries/subscriptions`                 | list / get details                         | `webhook_subscription_read` |
| `/api/v1/event-deliveries/subscriptions`                 | create, update, patch activate, deactivate | `webhook_subscription_edit` |
| `/api/v1/event-deliveries/subscriptions/{id}/deliveries` | view deliveries for one subscription       | `delivery_audit_read`       |
| `/api/v1/event-deliveries/deliveries`                    | list / get delivery details                | `delivery_audit_read`       |
| `/api/v1/event-deliveries/env-variables`                 | list / get details                         | `webhook_subscription_read` |
| `/api/v1/event-deliveries/env-variables`                 | create, update, delete                     | `webhook_subscription_edit` |

**Minimum Required Permissions**

For users who only configure webhooks:

* `webhook_subscription_read`
* `webhook_subscription_edit`

**Investigating Delivery Issues**

To view delivery attempts, failures, and retries:

* `delivery_audit_read`

### Role Assignment

These permissions were included in the **Event Publisher** permission in the [**Fynapse REST API Client**](/documentation/instance-management/security/default-system-roles/fynapse-rest-api-client#event-publisher) role available by default in Fynapse.

Ensure that:

* users configuring webhooks have this role assigned
* or an equivalent custom role with these permissions