Receive Webhooks

Filed sends workspace-scoped task status events to HTTPS endpoints you configure. Use webhooks when your integration needs status changes without polling the tasks API. Each delivery includes the Filed workspace ID, client ID, and task ID. Use all three identifiers when matching an event to your own records. Filed uses Svix for signing, retries, delivery history, and replay.

Supported events

Event names are derived directly from the task status:

Event	Status	Meaning
`task.running`	`RUNNING`	A supported task started running.
`task.completed`	`COMPLETED`	A supported task completed successfully.
`task.failed`	`FAILED`	A supported task failed.

These events apply only to Binder (BINDER), Tax Prep (TAX_PREP), Tax Review (TAX_REVIEW), Tax Advisor (TAX_ADVISOR), and Tax Prep Lite (TAX_PREP_LITE). You can retrieve this information programmatically with webhookEventCatalog.

1. Configure an endpoint

Open Settings > Webhooks in the Filed workspace. You must be a workspace administrator. Add your HTTPS receiver URL, select the events you need, and copy the endpoint signing secret.

Store the signing secret in a secrets manager. Filed shows it when the endpoint is created or its secret is rotated. Do not put it in source control or expose it to browser code.

You can also manage endpoints through the createWebhookEndpoint and related GraphQL mutations.

2. Receive the payload

Every event uses the same version 1 envelope:

{
  "id": "33df4504-a6c5-5587-b231-0b56f29d0638",
  "event": "task.completed",
  "version": "1",
  "occurredAt": "2026-08-19T12:00:00.000Z",
  "workspaceId": "019f0fb2-42d9-72e0-b7ac-78b32ad45ef1",
  "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
  "taskId": "018f9c2b-7c4d-7e10-9a22-6b3c4d5e6f70",
  "taskType": "TAX_PREP",
  "status": "COMPLETED",
  "errorMessage": null
}

String!

A deterministic UUID for this task status event. Use the webhook-id header for delivery deduplication.

String!

The event name: task.running, task.completed, or task.failed.

String!

The payload schema version. The current value is 1.

String!

The ISO 8601 time when the task entered the status.

ID!

The Filed workspace that owns the task and endpoint.

ID!

The Filed client associated with the task.

ID!

The Filed task whose status changed.

String!

One of BINDER, TAX_PREP, TAX_REVIEW, TAX_ADVISOR, or TAX_PREP_LITE.

String!

One of RUNNING, COMPLETED, or FAILED. The status always matches the event suffix.

String

The failure detail for task.failed. It is null for running and completed events.

3. Verify the signature

Verify the raw request body before parsing JSON or changing application state. Svix signs each request with the webhook-id, webhook-timestamp, and webhook-signature headers.

import { Webhook } from "svix";

const secret = process.env.FILED_WEBHOOK_SECRET;

export async function receiveFiledWebhook(request: Request) {
  if (!secret) throw new Error("FILED_WEBHOOK_SECRET is not configured");

  const body = await request.text();
  const payload = new Webhook(secret).verify(body, {
    "webhook-id": request.headers.get("webhook-id") ?? "",
    "webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
    "webhook-signature": request.headers.get("webhook-signature") ?? "",
  });

  return Response.json({ accepted: true }, { status: 200 });
}

Do not verify a re-serialized JSON object. Whitespace or key ordering changes will invalidate the signature. Pass the exact raw request bytes to the Svix verification library.

4. Handle duplicates and retries

Webhook delivery is at least once. Store the webhook-id header in a table with a uniqueness constraint before applying the event. If you have already handled that ID, return a successful response without applying it again. Return a 2xx response promptly after durable acceptance. Move slow work to a queue. Svix retries failed deliveries and lets workspace administrators inspect or replay attempts from Settings > Webhooks.

Treat events as notifications, not as the only task record. If you need to reconcile state, query the task by its taskId through the tasks API.

5. Rotate a signing secret

Rotate a secret from Settings > Webhooks or with rotateWebhookEndpointSecret. The API defaults to a 24-hour grace period during which both the old and new secrets are valid. Deploy the new secret to your receiver before the grace period ends. Remove the old secret after you confirm deliveries are being verified with the new one.

Guides

Recipes

Supported events

1. Configure an endpoint

2. Receive the payload

3. Verify the signature

4. Handle duplicates and retries

5. Rotate a signing secret

​Supported events

​1. Configure an endpoint

​2. Receive the payload

​3. Verify the signature

​4. Handle duplicates and retries

​5. Rotate a signing secret

Supported events

1. Configure an endpoint

2. Receive the payload

3. Verify the signature

4. Handle duplicates and retries

5. Rotate a signing secret