Webhooks

Webhooks allows you to integrate Cubicl with other applications. Cubicl notifies the webhook URL you added each time the type of action you chose happens.

• When client is created,

• When client is deleted,

• When task is created,

• When task is updated,

• When task is deleted,

• When post is created in task,

• When task state is changed,

• When task is archived,

• When the task is restored, the URL you added will be notified.

To add webhooks to Cubicl, first click on Others in the Navigation Menu, then the Integration button. In the page that opens, you can add your webhook URLs related to the specified actions in the Webhook Settings table. If you're using applications like Zapier, Pabbly Connect, etc., paste the link you get from these platforms into the URL field. If you're integrating into your own system, provide a URL from your system.

After you've added the URL, select the type of action from the list that will trigger the notification. If it's a task-related action, you must also associate it with a project. Once this is done, click save to create a record of the webhook for the selected action type. Cubicl will then notify this URL each time the chosen action occurs.

Endpoints

Another way of creating and interacting with webhooks is using our API.

Get Webhooks

GET https://cubicl.io/api/v1/users/self/webhook

Returns webhook records related to the currently authenticated user.

200: OK Webhooks

Webhook[]

Create Webhook

POST https://cubicl.io/api/v1/users/self/webhook

Request Body

Name	Type	Description
group	string	When a webhook type related to tasks is selected, a project id must be entered.
type*	WebhookType	The type of event that will trigger the webhook. This must be one of the predefined event types that your system supports.
url*	string	The URL to which the webhook events will be sent. This must be a valid URL, and the endpoint should be prepared to accept the payloads for the events it's subscribed to.

200: OK New webhook details

Webhook

422: Unprocessable Entity Invalid operation

{
    // 2: Project id is required for webhooks related to tasks.
    // 118: Webhook type is not supported.
    code: number
}

Update Webhook

PUT https://cubicl.io/api/v1/users/self/webhook/:id

Updates a webhook with given details. All details are optional. Only given fields are updated.

Path Parameters

Name	Type	Description
id*	string	Webhook id

Request Body

Name	Type	Description
group	string	When a webhook type related to tasks is selected, a project id must be entered.
type	WebhookType	The type of event that will trigger the webhook. This must be one of the predefined event types that your system supports.
url	string	The URL to which the webhook events will be sent. This must be a valid URL, and the endpoint should be prepared to accept the payloads for the events it's subscribed to.

200: OK New webhook details

Webhook

404: Not Found Webhook with the given ID cannot be found

422: Unprocessable Entity Invalid operation

{
    // 118: Webhook type is not supported.
    code: number
}

Delete Webhook

DELETE https://cubicl.io/api/v1/users/self/webhook/:id

Deletes the webhook with given id.

Path Parameters

Name	Type	Description
id*	string	Webhook id

200: OK Empty response

404: Not Found Webhook with the given ID cannot be found

Webhook Formats

When Task is Updated

{
    oldTask: Task,
    updatedTask: Task
}

When Post is Created in Task

{
    activity: TaskActivity,
    task: Task
}

When Task State is Changed

{
    newState: TaskState,
    oldState: TaskState,
    task: Task
}

When Task is Created, Deleted, Archived or Restored

{
    task: Task
}

When Client is Created or Deleted

{
    customers: Customer[]
}

Data

Webhook

type Webhook = {
    _id: string;
    type: WebhookType;
    url: string;
    group: string; // Project id
    user: string; // User id
    createdAt: number;
    updatedAt: number;
}

Webhook Type

type WebhookType = 'customer-created' | 'customer-deleted'
    | 'task-created'
    | 'task-updated'
    | 'task-deleted'
    | 'posted-on-task'
    | 'task-state-changed'
    | 'task-archived'
    | 'task-restored';

Task

type Task = {
    _id: string;
    name: string;
    desc: string;
    state: string;
    start: number | null; // Start date
    deadline: number | null;
    assignees: User[];
    assignedBy: User; // Owner
    followers: User[];
    // Portal users who follow this task if task is shared in
    // the client portal.
    portalFollowers?: PortalUser[];
    // From 1 to 5. 5 is the highest.
    priority: number;
    // A score to sort same-priority tasks among themselves. 
    // Lowest score is shown at the top.
    priorityScore: number;
    // Project
    group: Project;
    // Organization
    org: Organization;
    /* none: Task has no steps
     * steps: Task has a checklist
     * progress: Task has a progress bar
     */
    stepType: 'none' | 'steps' | 'progress';
    // Check below for definitions of these types.
    steps?: CheckList | ProgressBar;
    customer: Customer | null,
    tags: Tag[];
    subtasks: Task[];
    parent: Task | null;
    // This property exists if task is created for an incoming email.
    email?: EmailUser;
    // This property exists if task is created for a support request
    // through the Client Portal feature.
    support?: PortalUser;
    private: boolean;
    recurrent?: boolean;
    sharedWithCustomer?: boolean;
    estimatedTime?: number; // Duration in seconds.
    // If task has custom fields, holds the name and value for each field.
    customFields?: {[fieldName: string]: string};
    // If task is recurrent, shows if this is the newest copy.
    lastCopy?: boolean;
    createdAt: number;
    updatedAt: number;
    completedAt?: number;
    archivedAt?: number | null;
    deleted_at?: number;
    // 'day month year, hours:minutes' format.
    createdAtFormatted: string;
    updatedAtFormatted: string;
    completedAtFormatted?: string;
    archivedAtFormatted?: string;
    deletedAtFormatted?: string;
}

Task Activity

type TaskActivity = {
    _id : string;
    // User who did the activity
    user: User;
    // Portal user who created the activity. Exists only when
    // activity is created in the Client Portal by a portal user.
    portalUser?: PortalUser;
    content: string;
    type = "post";
    // If activity is a reply to a previous post, keeps the referenced activity id.
    replyToId?: string;
    // Whether the activity (post) is shared with a Client Portal user.
    customerCanSee: boolean;
    // List of users mentioned in the post.
    mentions: Mention[];
}

Task State

type TaskState = {
    name: string;
    type: 'waiting' | 'active' | 'completed' | 'suspended';
    color: string; // Hex color code.
    textColor: string; // Hex color code.
    // Shows whether this is the state tasks will be created in when the task
    // state is not specified in Create Task endpoint.
    isDefault?: boolean;
}

Client

type Customer = {
    _id: string;
    name: string; // A short name shown in UI and used for search
    phone: string | null;
    email: string | null;
    fullname: string | null;
    // People working at this client you are in contact with
    contacts: Contact[];
    // An object where keys are custom field ids and values are field values
    // customFields can be null
    customFields: {
        [fieldId: string]: string | null
    } | null;
    tax : {
        administration?: string;
        number?: string;
        address?: string;
    }
    createdBy: User;
    // List of users who get notifications for activities from portal users
    // of this client
    portalCustomerManagerIds: User[];
    org: Organization;
    createdAt: number;
    updatedAt: number;
    deleted_at?: number;
    // 'day month year, hours:minutes' format.
    createdAtFormatted: string;
    updatedAtFormatted: string;
    deletedAtFormatted?: string;
}

Contacts

type Contact = {
    name: string;
    position: string;
    phone: string;
    email: string;
}

Task Steps

type ProgressBar = {
    completed: number;
    total: number;
}

type CheckList = TaskStep[];

type TaskStep = {
    id: string;
    name: string;
    desc?: string;
    assignees: string[]; // Ids of the step assignees
    /* Task steps are recursive. They can have sub-steps too.
     * If not set, the step has no sub-steps.
     * If 'steps', a property named 'steps' holds sub-steps.
     * If 'progress', this step object has a property named 'total'.
     */
    stepType?: 'steps' | 'progress';
    steps?: CheckList;
    // If 'stepType' is 'progress', this is a number and indicates the total number
    // of steps in the bar. Otherwise, a boolean to indicate completion.
    completed: boolean | number;
    // Set when 'stepType' is 'progress'
    total?: number;
}
    

Tag

type Tag = {
    _id: string;
    color: string;
    group: string;
    name: string;
    textColor: string;
    updatedAt: number;
}

User

type User = {
    _id : string;
    firstname: string;
    lastname: string;
    email: string;
    profile: string; // URL for profile photo
    jobTitle: string;
    createdAt: number;
}

Portal User

type PortalUser = {
    _id : string;
    firstname: string;
    lastname: string;
    email: string;
    profile: string; // URL for profile photo
    createdAt: number;
}

Email User

type EmailUser = {
    _id : string;
    firstname: string;
    lastname: string;
    email: string;
    createdAt: number;
}

Organization

type Organization = {
    _id : string;
    name: string;
    fullname: string;
    group: string;
    admins: string[];
    employees: string[];
    createdAt: number;
}

Project

type Project = {
    _id: string;
    name: string;
     // Projects can have multiple parents. The root project has no parents.
    parents: string[] | null;
    // Admin user ids.
    admins: string[];
     // Member user ids.
    members: string[];
     // Child group ids.
    groups: string[];
    // Task state definitions. Exists only when states are customized. Read
    // Task States section for more info.
    taskStates?: TaskState[];
    // Permissions set in the project. Only exists when project permissions
    // are customized. Read the Permissions section for more info.
    perms?: {
        members: PermissionLevels,
        everybody: PermissionLevels,
        // An object where keys are userIds and values are permission levels object.
        users?: {
            [userId: string]: PermissionLevels,
        }
    },
    customTaskFields? : CustomTaskField[];
    private: boolean;
    orgId: string;
    estimatedTimeEnabled: boolean;
    createdAt: number;
    updatedAt: number;
}

Custom Task Field

type CustomTaskField = {
    _id : string;
    name: string;
    type: string;
    deleted: boolean;
}