Webhooks - Filed Engineering

Use the Webhooks API to discover supported events and manage delivery endpoints. Endpoint operations require an administrator’s read-write workspaceToken. See Receive 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.

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:

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

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

mutation CreateWebhookEndpoint($input: CreateWebhookEndpointInput!) {
  createWebhookEndpoint(input: $input) {
    endpoint {
      id
      url
      enabled
      eventTypes
    }
    signingSecret
  }
}

{
  "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

mutation UpdateWebhookEndpoint($input: UpdateWebhookEndpointInput!) {
  updateWebhookEndpoint(input: $input) {
    id
    url
    description
    enabled
    eventTypes
    updatedAt
  }
}

{
  "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

mutation DeleteWebhookEndpoint($endpointId: ID!) {
  deleteWebhookEndpoint(endpointId: $endpointId)
}

endpointId is required. The mutation returns true after deletion.

Rotate a signing secret

mutation RotateWebhookSecret($input: RotateWebhookEndpointSecretInput!) {
  rotateWebhookEndpointSecret(input: $input) {
    endpoint {
      id
      url
    }
    signingSecret
  }
}

{
  "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.

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.

​Event catalog

​Endpoint fields

​List endpoints

​Create an endpoint

​Update an endpoint

​Delete an endpoint

​Rotate a signing secret

​Open the management portal