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`	`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:

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.

​Event catalog

​Endpoint fields

​List endpoints

​Create an endpoint

​Update an endpoint

​Delete an endpoint

​Rotate a signing secret