> For the complete documentation index, see [llms.txt](https://docs.cubicl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cubicl.io/api-integration/webhooks.md).

# Webhooks

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

The URL you added will be notified:

* When a client is created
* When a client is updated
* When a client is deleted
* When a task is created
* When a task is updated
* When a task is deleted
* When a post is created on a task
* When a task state is changed
* When a task is archived
* When a task is restored
* When a chat message is received
* When an in-app notification is received

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

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/users/self/webhook`

Returns webhook records related to the currently authenticated user.

{% tabs %}
{% tab title="200: OK Webhooks" %}

```typescript
Webhook[]
```

{% endtab %}
{% endtabs %}

### Create Webhook

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | WebhookType | The type of event that will trigger the webhook. This must be one of the predefined event types that your system supports.                                                |
| url<mark style="color:red;">\*</mark>  | 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. |

{% tabs %}
{% tab title="200: OK New webhook details" %}

```typescript
Webhook
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid operation" %}

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

{% endtab %}
{% endtabs %}

### Update Webhook

<mark style="color:orange;">`PUT`</mark> `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<mark style="color:red;">\*</mark> | 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. |

{% tabs %}
{% tab title="200: OK New webhook details" %}

```typescript
Webhook
```

{% endtab %}

{% tab title="404: Not Found Webhook with the given ID cannot be found" %}

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid operation" %}

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

{% endtab %}
{% endtabs %}

### Delete Webhook

<mark style="color:red;">`DELETE`</mark> `https://cubicl.io/api/v1/users/self/webhook/:id`

Deletes the webhook with given id.

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | Webhook id  |

{% tabs %}
{% tab title="200: OK Empty response" %}

{% endtab %}

{% tab title="404: Not Found Webhook with the given ID cannot be found" %}

{% endtab %}
{% endtabs %}

### Webhook Formats

#### When Task is Updated

```typescript
{
    oldTask: Task,
    updatedTask: Task
}
```

#### When Post is Created in Task

```typescript
{
    activity: TaskActivity,
    task: Task
}
```

#### When Task State is Changed

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

#### When Task is Created, Deleted, Archived or Restored

```typescript
{
    task: Task
}
```

#### When Client is Created or Deleted

```typescript
{
    customers: Customer[]
}
```

## Data

### Webhook

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

### Webhook Type

```typescript
type WebhookType =
    | 'customer-created'
    | 'customer-updated'
    | 'customer-deleted'
    | 'task-created'
    | 'task-updated'
    | 'task-deleted'
    | 'posted-on-task'
    | 'task-state-changed'
    | 'task-archived'
    | 'task-restored'
    | 'chat-message-received'
    | 'notification-received';
```

### [**Task**](https://docs.cubicl.io/api-integration/tasks#task)

### [**Task Activity**](https://docs.cubicl.io/api-integration/tasks#task-activity)

### [**Task State**](https://docs.cubicl.io/api-integration/tasks#task-state)

### [**Task Steps**](https://docs.cubicl.io/api-integration/tasks#task-steps)

### [**Client**](https://docs.cubicl.io/api-integration/clients#clients)

### [**Contacts**](https://docs.cubicl.io/api-integration/clients#contacts)

### [**Project**](https://docs.cubicl.io/api-integration/projects#project)

### [**Custom Task Fields**](https://docs.cubicl.io/api-integration/projects#custom-task-fields)

### [**User**](https://docs.cubicl.io/api-integration/users#users)

### **Tag**

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

### **Organization**

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

### [**Chat Message**](https://docs.cubicl.io/api-integration/chat#chat-messages)