Working with Webhook events

Before you dive into the various event types, make sure to follow these key steps:

Start by exploring our guide Getting started with Webhooks.
Important: We strongly recommend not relying solely on the data provided in the webhook payload. Make an API call to retrieve the necessary data in the most accurate way. To learn more, see our best practices.

Task Events

Use the following events to receive notifications about triggered task lists and tasks status updates.

Event	Type	Description
Task List Triggered	todo.assign	All general tasks triggered upon a task list trigger.
Task Status Changed	todo.changedStatus	Any change in the status of a general task - completed/incomplete

Note: As best practice we recommend to use the event as a notification only, and retrieve the complete task details by using the Read tasks of a specific employee API endpoint. Use the employee ID (which is returned in the "toDoAssigneeId" in the event's payload), to filter the API response.

Task List Triggered Payload

{
  "companyId": 1,
  "changedBy": {
    "id": "2471054914621538305",
    "companyId": 1,
    "firstName": "Luke",
    "surname": "Skywalker",
    "email": "[email protected]",
    "displayName": "Luke Skywalker",
    "site": "Hong Kong (Demo)",
    "siteId": 3
  },
  "toDos": [
    {
      "id": 9677,
      "owner": {
        "id": "2471054969701138446",
        "firstName": "Frederick",
        "surname": "Bateson",
        "email": "[email protected]",
        "displayName": "Frederick Bateson"
      },
      "title": "Set a 'first friday' night out",
      "requestedFor": {
        "id": "2471054981302583315",
        "firstName": "Austin",
        "surname": "Legge",
        "email": "[email protected]",
        "displayName": "Austin Legge"
      },
      "due": "2021-04-11",
      "linkInBob": null,
      "set": "Onboarding",
      "workflow": "Onboarding",
      "ordinalInWorkflow": 9,
      "description": "How was week one for your new starter(s)? To welcome them properly, invite them out for a drink on their 'First Friday'",
      "status": "Open",
      "completionDate": null
    },
    {
      "id": 9680,
      "owner": {
        "id": "2471054914621538305",
        "firstName": "Bob",
        "surname": "Skywalker",
        "email": "[email protected]",
        "displayName": "Bob Skywalker"
      },
      "title": "Send intro email to the company",
      "requestedFor": {
        "id": "2471054981302583315",
        "firstName": "Austin",
        "surname": "Legge",
        "email": "[email protected]",
        "displayName": "Austin Legge"
      },
      "due": "2021-04-09",
      "linkInBob": null,
      "set": "Onboarding",
      "workflow": "Onboarding",
      "ordinalInWorkflow": 11,
      "description": "Make new starters feel like they belong by sending a welcome email to the entire company. The little things can make all the difference",
      "status": "Open",
      "completionDate": null
    }
    ],
  "requestedFor": {
    "id": "2471054981302583315",
    "companyId": 1,
    "firstName": "Austin",
    "surname": "Legge",
    "email": "[email protected]",
    "displayName": "Austin Legge",
    "site": "New York (Demo)",
    "siteId": 2
  },
  "pivotDate": "2021-04-08",
  "assignmentType": "manually",
  "workflow": {
    "id": 1,
    "name": "Onboarding",
    "message": "<div>This is an onboarding tasklist</div>",
    "automaticTriggerEnabled": false,
    "automaticTrigger": {},
    "filter": [
      {
        "fieldPath": "/internal/lifecycleStatus",
        "operator": "text_equals",
        "values": [
          "employed"
        ]
      }
    ],
    "owner": "2471054979121545234"
  },
  "type": "todo.assign",
  "creationDate": "2021-04-08T10:47:02.087"
}

Task Status Changed Payload

{
  "companyId": 4765676,
  "changedById": "2471054914621538305",
  "changedByName": "Bob Skywalker",
  "newStatus": "Closed",	// task's new status
  "toDoId": [	// task internal id
    28805776
  ],
	"toDoRequestedForId": [		
    "247105491462156754"
  ],
  "toDoAssigneeId": [
    "2471054914621538305"
  ],
  "toDoAssigneeName": [
    "John Mann"
  ],
  "toDoTitle": [
    "Open company email for ne"	// truncated to 25 characters
  ],
  "type": "todo.changedStatus",
  "modificationDate": "2021-04-07T14:26:36.547"
}

Note: The Webhook event payload may contain truncated values (such as the task description or title) in case they are long. Use the Read tasks of a specific employee API endpoint to read the complete task details.