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

# Webhooks

> Read the webhook catalog and manage workspace endpoints through GraphQL

Use the Webhooks API to discover supported events and manage delivery
endpoints. Endpoint operations require an administrator's read-write
`workspaceToken`. See [Receive Webhooks](/guides/webhooks) for payload and
signature verification guidance.

All operations use `https://router.apps.filed.com/graphql`.

## Event catalog

`Query.webhookEventCatalog` is global and does not accept a workspace ID.

```graphql theme={null}
query WebhookEventCatalog {
  webhookEventCatalog {
    name
    description
    version
    status
    taskTypes
    payloadSchema
  }
}
```

| Event               | Status      | Version | Supported task types                                               |
| ------------------- | ----------- | ------- | ------------------------------------------------------------------ |
| `task.running`      | `RUNNING`   | `2`     | `BINDER`, `TAX_PREP`, `TAX_REVIEW`, `TAX_ADVISOR`, `TAX_PREP_LITE` |
| `task.completed`    | `COMPLETED` | `2`     | `BINDER`, `TAX_PREP`, `TAX_REVIEW`, `TAX_ADVISOR`, `TAX_PREP_LITE` |
| `task.failed`       | `FAILED`    | `2`     | `BINDER`, `TAX_PREP`, `TAX_REVIEW`, `TAX_ADVISOR`, `TAX_PREP_LITE` |
| `subtask.completed` | `COMPLETED` | `2`     | `BINDER`, `TAX_PREP`, `TAX_REVIEW`, `TAX_ADVISOR`, `TAX_PREP_LITE` |
| `subtask.failed`    | `FAILED`    | `2`     | `BINDER`, `TAX_PREP`, `TAX_REVIEW`, `TAX_ADVISOR`, `TAX_PREP_LITE` |
| `documents.synced`  | —           | `2`     | —                                                                  |

| Field           | Type        | Description                                                                      |
| --------------- | ----------- | -------------------------------------------------------------------------------- |
| `name`          | `String!`   | Stable event name.                                                               |
| `description`   | `String!`   | When Filed emits the event.                                                      |
| `version`       | `String!`   | Payload schema version.                                                          |
| `groupName`     | `String!`   | Event family, such as `Tasks` or `Documents`.                                    |
| `status`        | `String`    | Task status represented by the event. Null for events that do not report a task. |
| `taskTypes`     | `[String!]` | Task types allowed to emit the event. Null for events not emitted by a task.     |
| `payloadSchema` | `JSON!`     | Complete JSON Schema for the event payload.                                      |

## Endpoint fields

All endpoint operations use this type:

```graphql theme={null}
type WebhookEndpoint {
  id: ID!
  url: String!
  description: String!
  enabled: Boolean!
  eventTypes: [String!]
  createdAt: Date!
  updatedAt: Date!
}
```

| Field         | Description                                                  |
| ------------- | ------------------------------------------------------------ |
| `id`          | Endpoint ID used for updates, deletion, and secret rotation. |
| `url`         | HTTPS delivery destination.                                  |
| `description` | Administrator-provided label.                                |
| `enabled`     | Whether the endpoint receives deliveries.                    |
| `eventTypes`  | Selected events. `null` means all current and future events. |
| `createdAt`   | Endpoint creation time.                                      |
| `updatedAt`   | Last endpoint update time.                                   |

## List endpoints

```graphql theme={null}
query WebhookEndpoints($limit: Int, $iterator: String) {
  me {
    ... on WorkspaceUser {
      workspace {
        webhookEndpoints(limit: $limit, iterator: $iterator) {
          data {
            id
            url
            description
            enabled
            eventTypes
            createdAt
            updatedAt
          }
          done
          iterator
        }
      }
    }
  }
}
```

| Argument   | Type     | Description                              |
| ---------- | -------- | ---------------------------------------- |
| `limit`    | `Int`    | Page size from 1 to 100. Defaults to 20. |
| `iterator` | `String` | Opaque iterator from the previous page.  |

The result contains `data`, `done`, and the next `iterator`. A `null`
iterator with `done: true` means there are no more pages.

## Create an endpoint

```graphql theme={null}
mutation CreateWebhookEndpoint($input: CreateWebhookEndpointInput!) {
  createWebhookEndpoint(input: $input) {
    endpoint {
      id
      url
      enabled
      eventTypes
    }
    signingSecret
  }
}
```

```json theme={null}
{
  "input": {
    "url": "https://partner.example.com/filed/webhooks",
    "description": "Production task events",
    "eventTypes": ["task.completed", "task.failed"]
  }
}
```

| Input field   | Type        | Description                                                                          |
| ------------- | ----------- | ------------------------------------------------------------------------------------ |
| `url`         | `String!`   | HTTPS receiver URL.                                                                  |
| `description` | `String`    | Optional administrator label.                                                        |
| `eventTypes`  | `[String!]` | Events to deliver. Omit for all current and future events. An empty list is invalid. |

The result contains the created `endpoint` and its `signingSecret`. Store the
secret immediately because Filed returns it only during creation or rotation.

## Update an endpoint

```graphql theme={null}
mutation UpdateWebhookEndpoint($input: UpdateWebhookEndpointInput!) {
  updateWebhookEndpoint(input: $input) {
    id
    url
    description
    enabled
    eventTypes
    updatedAt
  }
}
```

```json theme={null}
{
  "input": {
    "endpointId": "ep_2xYExample",
    "enabled": false
  }
}
```

| Input field   | Type        | Description                                                                     |
| ------------- | ----------- | ------------------------------------------------------------------------------- |
| `endpointId`  | `ID!`       | Endpoint to update.                                                             |
| `url`         | `String`    | Replacement receiver URL.                                                       |
| `description` | `String`    | Replacement label. Pass `null` to clear it.                                     |
| `enabled`     | `Boolean`   | Set `false` to pause delivery.                                                  |
| `eventTypes`  | `[String!]` | Replacement subscription. Pass `null` for all events. An empty list is invalid. |

Provide at least one field besides `endpointId`. The mutation returns the
updated endpoint.

## Delete an endpoint

```graphql theme={null}
mutation DeleteWebhookEndpoint($endpointId: ID!) {
  deleteWebhookEndpoint(endpointId: $endpointId)
}
```

`endpointId` is required. The mutation returns `true` after deletion.

## Rotate a signing secret

```graphql theme={null}
mutation RotateWebhookSecret($input: RotateWebhookEndpointSecretInput!) {
  rotateWebhookEndpointSecret(input: $input) {
    endpoint {
      id
      url
    }
    signingSecret
  }
}
```

```json theme={null}
{
  "input": {
    "endpointId": "ep_2xYExample",
    "gracePeriodSeconds": 86400
  }
}
```

| Input field          | Type  | Description                                                                                 |
| -------------------- | ----- | ------------------------------------------------------------------------------------------- |
| `endpointId`         | `ID!` | Endpoint whose secret will be rotated.                                                      |
| `gracePeriodSeconds` | `Int` | Time during which the old secret remains valid. Defaults to 86400 and cannot exceed 604800. |

The result contains the endpoint and new `signingSecret`. Deploy the new secret
before the grace period ends.

## Open the management portal

`createWebhookPortalSession` returns a short-lived URL for Svix's hosted portal,
where an administrator can manage endpoints, view and roll signing secrets, and
inspect or replay past delivery attempts. It takes no arguments — the workspace
comes from the token.

```graphql theme={null}
mutation CreateWebhookPortalSession {
  createWebhookPortalSession {
    url
    expiresAt
  }
}
```

| Field       | Type      | Description                                                                                                                 |
| ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |
| `url`       | `String!` | Portal URL. It authenticates whoever opens it, so treat it as a credential: do not log it or pass it through a third party. |
| `expiresAt` | `Date!`   | One hour after creation.                                                                                                    |

The session grants exactly the portal's endpoint-management, secret-viewing and
attempt-replay capabilities, so it can do everything the mutations on this page
do — mint it only for an administrator who is about to use it.

Portal sessions need Svix credentials in the environment. Unlike delivery, which
degrades quietly when Svix is unconfigured, this mutation fails outright.