How to Set Up and Use Webhooks

Webhooks allow you to send real-time data from the platform to external systems when specific events occur. They are essential for automation and seamless integration with other tools.

Steps to Configure Webhooks

1. Navigate to the Webhooks Configuration Section

• In the Settings section of the sidebar, locate and select the "Integrations" option.
• Open the Webhook settings tab.

2. Configure Entity Events

• In the Integrations settings, you need to add a new integration:

  • Select integration provider "Flows API webhook".

  • Configure events for:

    • Packet events: Select the packet events you want to track.
    • Pipeline events: Choose the pipeline events you want to track.
    • Users events: Select the user events you want to track.
    • Entity events: Choose the entity events you want to track.
    • Packet comments events: Select events to track when comments are added, updated, or deleted on packets.
    • Projects events: Choose the project events you want to track.
    • Pipeline labels events: Select events for pipeline label changes.
    • Packet labels events: Choose events for packet label changes.

    (The events available for tracking are created, updated, and deleted.)

Check the relevant boxes to enable the events you want the webhook to track.

3. Set the Webhook Secret

• In the Secret field, enter a secure string. This secret will be used to authenticate webhook requests sent to your specified URL.
  • Example: 12345678

4. Save the Configuration

• Once all settings are adjusted, click the "Save" button to activate the webhook.

---

Testing Webhook Integration

1. View the Form RAW Response

• After configuration, the platform provides a Form RAW Response JSON preview to help validate the setup.
• The JSON will include details such as:
  • softRemoved: Indicates if the event item was soft deleted.
  • status: Current status of the item.
  • integrationProvider: Metadata about the integration provider, including the path and segments.

2. Expected Webhook Payload

When an event you have subscribed to occurs, the platform will send a POST request to your specified webhook URL. The payload will be in JSON format and will contain detailed information about the event. Below is an example of the expected webhook payload:

{
  "eventTimestamp": "ISO8601 Timestamp",
  "operationType": "created | updated | deleted",
  "entityPath": "string",
  "entityId": "string",
  "entityKey": "string",
  "collectionPath": "string",
  "organizationId": "string",
  "data": {
    "value": {
      "key": "string",
      "properties": {
        // Key-value pairs representing the entity's properties
      },
      "createTime": "ISO8601 Timestamp",
      "updateTime": "ISO8601 Timestamp"
    },
    "oldValue": {
      "key": "string",
      "properties": {
        // Previous state of the entity's properties
      },
      "createTime": "ISO8601 Timestamp",
      "updateTime": "ISO8601 Timestamp"
    },
    "updateMask": [
      // List of fields that were changed during an update
    ]
  }
}

Payload Field Descriptions with Expected Types

• eventTimestamp (string): The timestamp when the event was triggered (ISO 8601 format).
• operationType (string): The type of operation that occurred (created, updated, or deleted).
• entityPath (string): The full path to the entity within the platform's data hierarchy.
• entityId (string): The unique identifier of the entity.
• entityKey (string): A key representing the category or type of the entity.
• collectionPath (string): The path to the collection containing the entity.
• organizationId (string): The ID of the organization.
• data (object): An object containing details about the entity's state.
  • value (object): The current state of the entity after the operation.
    • key (string): The unique key of the entity.
    • properties (object): Key-value pairs of the entity's properties and metadata.
    • createTime (string): The timestamp when the entity was created (ISO 8601 format).
    • updateTime (string): The timestamp when the entity was last updated (ISO 8601 format).
  • oldValue (object, optional): The previous state of the entity before the operation (only available for updated and deleted events).
    • key (string): The unique key of the entity.
    • properties (object): Key-value pairs of the entity's previous properties.
    • createTime (string): The timestamp when the entity was created (ISO 8601 format).
    • updateTime (string): The timestamp when the entity was last updated (ISO 8601 format).
  • updateMask (array of strings, optional): An array listing the fields that were changed during an update operation.

Packet Comments Events Payload

When you subscribe to packet comments events, the webhook payload will include specific information about the comment operation. The entityPath will follow the pattern pipelinesPackets/{packetId}/comments/{commentId}, and the payload will include:

{
  "eventTimestamp": "(string) The timestamp when the event was triggered",
  "entityId": "(string) The unique identifier of the comment",
  "entityKey": "(string) The type of entity, in this case 'flows/comments'",
  "entityPath": "(string) The full path to the comment in the data hierarchy",
  "collectionPath": "(string) The path to the comments collection",
  "organizationId": "(string) The ID of the organization",
  "operationType": "(string) The type of operation - 'created', 'updated', or 'deleted'",
  "entityComments": "(array) Array of related comments",
  "organizationId": "(string) The ID of the organization",
  "data": {
    "value": {
      "key": "(string) The unique key/path of the comment",
      "properties": {
        "replies": "(array) Array of reply comments",
        "content": "(string) The comment text content",
        "parentCommentRef": "(string|null) Reference to parent comment if this is a reply",
        "softRemoved": "(boolean) Whether comment is soft deleted",
        "createdBy": "(string) Reference to the user who created the comment",
        "createdAt": "(string) ISO timestamp of comment creation"
      },
      "createTime": "(string) ISO timestamp when record was created",
      "updateTime": "(string) ISO timestamp when record was last updated"
    },
    "oldValue": "(object|null) Previous state for updates/deletes",
    "updateMask": "(array|null) Fields changed in update"
  }
}

This allows you to track all comment-related activities on packets and integrate them with your external systems.