> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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`   | `1`     | `BINDER`, `TAX_PREP`, `TAX_REVIEW`, `TAX_ADVISOR`, `TAX_PREP_LITE` |
| `task.completed` | `COMPLETED` | `1`     | `BINDER`, `TAX_PREP`, `TAX_REVIEW`, `TAX_ADVISOR`, `TAX_PREP_LITE` |
| `task.failed`    | `FAILED`    | `1`     | `BINDER`, `TAX_PREP`, `TAX_REVIEW`, `TAX_ADVISOR`, `TAX_PREP_LITE` |

| Field           | Type         | Description                                 |
| --------------- | ------------ | ------------------------------------------- |
| `name`          | `String!`    | Stable event name.                          |
| `description`   | `String!`    | When Filed emits the event.                 |
| `version`       | `String!`    | Payload schema version.                     |
| `status`        | `String!`    | Task status represented by the event.       |
| `taskTypes`     | `[String!]!` | Task types allowed to emit the event.       |
| `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.