Task status transitioned - Plain Docs

This event is fired when a task’s status changes (for example, moving to DONE or CANCELLED). A status change also fires task.task_updated.

Schema

View JSON Schema → Example:

{
  "timestamp": "2026-09-11T15:40:22.884Z",
  "workspaceId": "w_01GST0W989ZNAW53X6XYHAY87P",
  "payload": {
    "eventType": "task.task_status_transitioned",
    "previousTask": {
      "id": "ta_01HD44FHMCDSSWE38N14FSYV6K",
      "ref": "T-123",
      "title": "Follow up on SSO setup knowledge gap",
      "description": "Customers keep asking how to configure SSO. Add a help center article.",
      "status": "TODO",
      "priority": 1,
      "companyId": null,
      "tenantId": null,
      "assignee": {
        "id": "u_01H1V4NA10RMHWFBXB6A1ZBYRA",
        "email": "sam@example.com",
        "fullName": "Sam",
        "publicName": "Sam",
        "status": "ONLINE",
        "statusChangedAt": "2026-09-11T09:00:00.000Z",
        "createdAt": "2023-06-01T09:29:48.903Z",
        "createdBy": {
          "actorType": "user",
          "userId": "u_01H1V4NA10RMHWFBXB6A1ZBYRA"
        },
        "updatedAt": "2023-06-01T09:29:48.903Z",
        "updatedBy": {
          "actorType": "user",
          "userId": "u_01H1V4NA10RMHWFBXB6A1ZBYRA"
        },
        "deletedAt": null,
        "deletedBy": null
      },
      "assignedAt": "2026-09-11T09:12:04.221Z",
      "sourceLinks": [
        {
          "id": "tsl_01HD4X6WMCJSD8EHWDRHZ8WYDT",
          "sourceType": "knowledge_gap",
          "sourceId": "kg_01ARZ3NDEKTSV4RRFFQ69G5FAV"
        }
      ],
      "createdAt": "2026-09-11T09:12:04.221Z",
      "createdBy": {
        "actorType": "machineUser",
        "machineUserId": "mu_01HD44FHMCDSSWE38N14FSYV6K"
      },
      "updatedAt": "2026-09-11T09:12:04.221Z",
      "updatedBy": {
        "actorType": "machineUser",
        "machineUserId": "mu_01HD44FHMCDSSWE38N14FSYV6K"
      },
      "deletedAt": null,
      "deletedBy": null
    },
    "task": {
      "id": "ta_01HD44FHMCDSSWE38N14FSYV6K",
      "ref": "T-123",
      "title": "Follow up on SSO setup knowledge gap",
      "description": "Customers keep asking how to configure SSO. Add a help center article.",
      "status": "DONE",
      "priority": 1,
      "companyId": null,
      "tenantId": null,
      "assignee": {
        "id": "u_01H1V4NA10RMHWFBXB6A1ZBYRA",
        "email": "sam@example.com",
        "fullName": "Sam",
        "publicName": "Sam",
        "status": "ONLINE",
        "statusChangedAt": "2026-09-11T09:00:00.000Z",
        "createdAt": "2023-06-01T09:29:48.903Z",
        "createdBy": {
          "actorType": "user",
          "userId": "u_01H1V4NA10RMHWFBXB6A1ZBYRA"
        },
        "updatedAt": "2023-06-01T09:29:48.903Z",
        "updatedBy": {
          "actorType": "user",
          "userId": "u_01H1V4NA10RMHWFBXB6A1ZBYRA"
        },
        "deletedAt": null,
        "deletedBy": null
      },
      "assignedAt": "2026-09-11T09:12:04.221Z",
      "sourceLinks": [
        {
          "id": "tsl_01HD4X6WMCJSD8EHWDRHZ8WYDT",
          "sourceType": "knowledge_gap",
          "sourceId": "kg_01ARZ3NDEKTSV4RRFFQ69G5FAV"
        }
      ],
      "createdAt": "2026-09-11T09:12:04.221Z",
      "createdBy": {
        "actorType": "machineUser",
        "machineUserId": "mu_01HD44FHMCDSSWE38N14FSYV6K"
      },
      "updatedAt": "2026-09-11T15:40:22.884Z",
      "updatedBy": {
        "actorType": "user",
        "userId": "u_01H1V4NA10RMHWFBXB6A1ZBYRA"
      },
      "deletedAt": null,
      "deletedBy": null
    }
  },
  "id": "pEv_01HD4X7BTCJSP3NGTBKYSWGPSY",
  "webhookMetadata": {
    "webhookTargetId": "whTarget_01HD4400VTDJQ646V6RY37SR7K",
    "webhookTargetVersion": "2026-09-11",
    "webhookDeliveryAttemptId": "whAttempt_01HD4XHSAX79QW8E34V86CKJRK",
    "webhookDeliveryAttemptNumber": 1,
    "webhookDeliveryAttemptTimestamp": "2026-09-11T15:40:23.512Z"
  },
  "type": "task.task_status_transitioned"
}

Using the Webhooks SDK

You can use the @team-plain/webhooks package to parse and verify this event with full type safety:

import { verifyPlainWebhook } from "@team-plain/webhooks";

const result = verifyPlainWebhook(rawBody, signature, secret);

if (result.error) {
  console.error(result.error.message);
} else {
  // result.data is fully typed with the event payload
  const event = result.data;
  console.log(event.eventType, event.payload);
}