Webhook Documentation

Webhook Specification

This document outlines the structure and format of the webhook events for Task, Milestone, and Matter entities. The webhook is triggered whenever these entities are created or updated, delivering the serialized data in JSON API format.

1. Overview

The webhook delivers updates on Matters, Milestones, and Tasks. These updates are triggered when any of these entities are created or modified, and the relevant serialized data is sent to the configured endpoint.

2. Webhook Events

The following events will trigger a webhook:

• matter.created: Triggered when a new matter is created.
• milestone.created: Triggered when a new milestone is created.
• task.created: Triggered when a new task is created.
• task.status.updated: Triggered when a task status is updated

The webhook payload will vary based on the type of event triggered.

3. Payload Structure

Each payload follows the JSON API format. The structure includes standard fields as well as any additional nested relationships or metadata.

3.1 Matter Payload

For matter.created events, the payload will contain the following fields:

• id: A unique identifier for the matter.
• name: The name of the matter.
• description: A brief description of the matter.
• jurisdictions: A list of jurisdictions related to the matter.
• types: A list of types associated with the matter.
• roles: A list of roles related to the matter.
• createdDate: The date and time when the matter was created.
• createdBy: The user who created the matter.

{
  "data": {
    "type": "matter",
    "id": "matter-id",
    "attributes": {
      "name": "Matter Name",
      "description": "Matter Description",
      "jurisdictions": ["US-NY", "US-NJ"],
      "types": ["Type 1", "Type 2"],
      "roles": {
        "OWNER": ["userId"]
      },
      "createdDate": 1738738738761,
      "createdBy": "userId",
      "tags"; [{
        "id": "1z2y3x4d",
        "label": "Source",
        "value": "Google Ads"
      }]
    }
  }
}

3.2 Milestone Payload

For milestone.created and milestone.updated events, the payload will include:

• id: A unique identifier for the milestone.
• name: The name of the milestone.
• status: The current status of the milestone.
• createdDate: The timestamp when the milestone was created.
• dueDate: The due date for the milestone.
• targetDate: The target date for the milestone.
• matter: A reference to the matter associated with the milestone.
• totalTasks: The total number of tasks linked to the milestone.
• completedTasks: The number of tasks that are marked as completed.
• pendingTasks: The number of tasks still pending.

{
  "data": {
    "type": "milestone",
    "id": "milestone-id",
    "attributes": {
      "name": "Milestone Name",
      "status": "Milestone Status",
      "createdDate": 1738738738761,
      "dueDate": 1738738738761,
      "targetDate": 1738738738761,
      "matter": {
        "data": {
          "type": "matter",
          "id": "matter-id"
        }
      },
      "totalTasks": 10,
      "completedTasks": 5,
      "pendingTasks": 5
    }
  }
}

3.3 Task Payload

For task.created and task.status.updated events, the payload will consist of:

• id: A unique identifier for the task.
• name: The name of the task.
• status: The current status of the task.
• createdDate: The timestamp when the task was created.
• dueDate: The due date for the task.
• lastModifiedBy: The user who last modified the task.
• lastModifiedDate: The timestamp of the last modification.
• createdBy: The user who created the task.
• assignees: A list of users assigned to the task.
• reviewers: A list of users who are reviewers for the task.
• milestone: A reference to the milestone associated with the task.
• matter: A reference to the matter associated with the task.

{
  "data": {
    "type": "task",
    "id": "task-id",
    "attributes": {
      "name": "Task Name",
      "status": "TODO",
      "createdDate": 1738738738761,
      "dueDate": 1738738738761,
      "lastModifiedBy": "userId",
      "lastModifiedDate": 1738738738761,
      "createdBy": "userId3",
      "assignees": ["userId1"],
      "reviewers": ["userId2"],
      "tags"; [{
        "id": "1a2b3c4d",
        "label": "Group",
        "value": "Alpha"
      }]
    },
    "relationships": {
      "milestone": {
        "data": {
          "type": "milestone",
          "id": "milestone-id"
        }
      },
      "matter": {
        "data": {
          "type": "matter",
          "id": "matter-id"
        }
      }
    }
  }
}

4. Webhook Request

Each webhook event will be sent as a POST request to the endpoint provided by the user. The request body will contain the appropriate payload based on the event.

5. Security

To secure webhook requests:

• X-Secret header can be included to authenticate requests when the webhook is created. The response must include the X-Secret header value. Failing to do so will disable the webhook.

7. Testing

To test webhook events:

• Use a sandbox environment to simulate webhook triggers.
• Tools such as Postman or Webhook.site can be used to inspect incoming payloads.

8. Versioning

Webhook payload formats may evolve over time. Ensure to check for versioning information in the response headers and refer to the changelog for updates.

9. Support

For additional help, please get in touch: support@hilveight.com