Update webhooks documentation

This commit is contained in:
Frederic Guillot
2016-07-23 19:21:32 -04:00
parent ca45b5592b
commit 8e6e335c9d
2 changed files with 401 additions and 244 deletions

View File

@@ -1,16 +1,10 @@
Web Hooks Webhooks
========= ========
Webhooks служат для взаимодействия с внешними приложениями. Webhook посылает уведомление стороннему приложению о событиях, которые произошли в Канборд. Webhooks служат для взаимодействия с внешними приложениями. Webhook посылает уведомление стороннему приложению о событиях, которые произошли в Канборд.
- Webhooks могут быть использованы для создания задач вызовом простого URL (Вы можете сделать это и при помощи API) - Webhooks могут быть использованы для создания задач вызовом простого URL (Вы можете сделать это и при помощи API)
- Обращение к внешнему приложению может происходить автоматически, когда наступает какое-либо событие в Канборд (создана задача, обновлен комментарий и т.д.) - Обращение к внешнему приложению может происходить автоматически, когда наступает какое-либо событие в Канборд (создана задача, обновлен комментарий и т.д.)
@@ -18,89 +12,36 @@ Webhooks служат для взаимодействия с внешними п
Как написать webhook приемник во внешнем приложении?[](#how-to-write-a-web-hook-receiver "Ссылка на этот заголовок") Как написать webhook приемник во внешнем приложении?[](#how-to-write-a-web-hook-receiver "Ссылка на этот заголовок")
--------------------------------------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------------------------------------
Все внутренние события в Канборде могут быть посланы во внешний URL. Все внутренние события в Канборде могут быть посланы во внешний URL.
- Webhook URL (url приемник внешнего приложения) может быть задан в **Настройки** -\> **Webhooks** -\> **Webhook URL** - Webhook URL (url приемник внешнего приложения) может быть задан в **Настройки** -\> **Webhooks** -\> **Webhook URL**
- Когда в Канборде происходит событие, Канборд обращается к указанному URL автоматически - Когда в Канборде происходит событие, Канборд обращается к указанному URL автоматически
- Данные конвертируются в формат JSON и передаются с помощью POST HTTP запроса - Данные конвертируются в формат JSON и передаются с помощью POST HTTP запроса
- Webhook ключ передается в составе запроса в виде строкового параметра. Таким образом, вы можете проверить, что запрос на самом деле пришел из Канборда. - Webhook ключ передается в составе запроса в виде строкового параметра. Таким образом, вы можете проверить, что запрос на самом деле пришел из Канборда.
- **Созданный вами URL должен среагировать в течении 1 секунды**. Это желательно сделать потому, что запросы являются синхронными (ограничения языка PHP) и возможны тормоза в пользовательском интерфейсе, если скрипт будет слишком медленный! - **Созданный вами URL должен среагировать в течении 1 секунды**. Это желательно сделать потому, что запросы являются синхронными (ограничения языка PHP) и возможны тормоза в пользовательском интерфейсе, если скрипт будет слишком медленный!
### Список поддерживаемых событий[¶](#list-of-supported-events "Ссылка на этот заголовок") ### Список поддерживаемых событий[¶](#list-of-supported-events "Ссылка на этот заголовок")
- comment.create
- comment.update
- comment.create (комментарий.создать) - comment.delete
- file.create
- task.move.project
- task.move.column
- comment.update (комментарий.обновить) - task.move.position
- task.move.swimlane
- task.update
- task.create
- file.create (файл.создать) - task.close
- task.open
- task.assignee_change
- subtask.update
- task.move.project (задача.переместить.проект) - subtask.create
- subtask.delete
- task_internal_link.create_update
- task_internal_link.delete
- task.move.column (задача.переместить.колонка)
- task.move.position (задача.переместить.место)
- task.move.swimlane (задача.переместить.дорожка)
- task.update (задача.обновить)
- task.create (задача.создать)
- task.close (задача.закрыть)
- task.open (задача.открыть)
- task.assignee\_change (задача.назначить\_изменить)
- subtask.update (подзадача.обновить)
- subtask.create (подзадача.создать)

View File

@@ -1,5 +1,5 @@
Web Hooks Webhooks
========= ========
Webhooks are useful to perform actions with external applications. Webhooks are useful to perform actions with external applications.
@@ -21,6 +21,7 @@ All internal events of Kanboard can be sent to an external URL.
- comment.create - comment.create
- comment.update - comment.update
- comment.delete
- file.create - file.create
- task.move.project - task.move.project
- task.move.column - task.move.column
@@ -33,6 +34,9 @@ All internal events of Kanboard can be sent to an external URL.
- task.assignee_change - task.assignee_change
- subtask.update - subtask.update
- subtask.create - subtask.create
- subtask.delete
- task_internal_link.create_update
- task_internal_link.delete
### Example of HTTP request ### Example of HTTP request
@@ -43,19 +47,65 @@ Content-Type: application/json
Connection: close Connection: close
{ {
"event_name": "task.move.column", "event_name": "task.move.column",
"event_data": { "event_data": {
"task_id": "1", "task_id": "4",
"project_id": "1", "task": {
"position": 1, "id": "4",
"column_id": "1", "reference": "",
"swimlane_id": "0", "title": "My task",
"src_column_id": "2", "description": "",
"dst_column_id": "1", "date_creation": "1469314356",
"date_moved": "1431991532", "date_completed": null,
"recurrence_status": "0", "date_modification": "1469315422",
"recurrence_trigger": "0" "date_due": "1469491200",
} "date_started": "0",
"time_estimated": "0",
"time_spent": "0",
"color_id": "green",
"project_id": "1",
"column_id": "1",
"owner_id": "1",
"creator_id": "1",
"position": "1",
"is_active": "1",
"score": "0",
"category_id": "0",
"priority": "0",
"swimlane_id": "0",
"date_moved": "1469315422",
"recurrence_status": "0",
"recurrence_trigger": "0",
"recurrence_factor": "0",
"recurrence_timeframe": "0",
"recurrence_basedate": "0",
"recurrence_parent": null,
"recurrence_child": null,
"category_name": null,
"swimlane_name": null,
"project_name": "Demo Project",
"default_swimlane": "Default swimlane",
"column_title": "Backlog",
"assignee_username": "admin",
"assignee_name": null,
"creator_username": "admin",
"creator_name": null
},
"changes": {
"src_column_id": "2",
"dst_column_id": "1",
"date_moved": "1469315398"
},
"project_id": "1",
"position": 1,
"column_id": "1",
"swimlane_id": "0",
"src_column_id": "2",
"dst_column_id": "1",
"date_moved": "1469315398",
"recurrence_status": "0",
"recurrence_trigger": "0"
}
} }
``` ```
@@ -80,26 +130,51 @@ Task creation:
```json ```json
{ {
"event_name": "task.create", "event_name": "task.create",
"event_data": { "event_data": {
"title": "Demo", "task_id": 5,
"description": "", "task": {
"project_id": "1", "id": "5",
"owner_id": "1", "reference": "",
"category_id": 0, "title": "My new task",
"swimlane_id": 0, "description": "",
"column_id": "2", "date_creation": "1469315481",
"color_id": "yellow", "date_completed": null,
"score": 0, "date_modification": "1469315481",
"time_estimated": 0, "date_due": "0",
"date_due": 0, "date_started": "0",
"creator_id": 1, "time_estimated": "0",
"date_creation": 1431991532, "time_spent": "0",
"date_modification": 1431991532, "color_id": "orange",
"date_moved": 1431991532, "project_id": "1",
"position": 1, "column_id": "2",
"task_id": 1 "owner_id": "1",
} "creator_id": "1",
"position": "1",
"is_active": "1",
"score": "3",
"category_id": "0",
"priority": "2",
"swimlane_id": "0",
"date_moved": "1469315481",
"recurrence_status": "0",
"recurrence_trigger": "0",
"recurrence_factor": "0",
"recurrence_timeframe": "0",
"recurrence_basedate": "0",
"recurrence_parent": null,
"recurrence_child": null,
"category_name": null,
"swimlane_name": null,
"project_name": "Demo Project",
"default_swimlane": "Default swimlane",
"column_title": "Ready",
"assignee_username": "admin",
"assignee_name": null,
"creator_username": "admin",
"creator_name": null
}
}
} }
``` ```
@@ -107,113 +182,121 @@ Task modification:
```json ```json
{ {
"event_name": "task.update", "event_name": "task.update",
"event_data": { "event_data": {
"id": "1", "task_id": "5",
"title": "Demo", "task": {
"description": "", "id": "5",
"date_creation": "1431991532", "reference": "",
"color_id": "yellow", "title": "My new task",
"project_id": "1", "description": "New description",
"column_id": "1", "date_creation": "1469315481",
"owner_id": "1", "date_completed": null,
"position": "1", "date_modification": "1469315531",
"is_active": "1", "date_due": "1469836800",
"date_completed": null, "date_started": "0",
"score": "0", "time_estimated": "0",
"date_due": "0", "time_spent": "0",
"category_id": "2", "color_id": "purple",
"creator_id": "1", "project_id": "1",
"date_modification": 1431991603, "column_id": "2",
"reference": "", "owner_id": "1",
"date_started": 1431993600, "creator_id": "1",
"time_spent": 0, "position": "1",
"time_estimated": 0, "is_active": "1",
"swimlane_id": "0", "score": "3",
"date_moved": "1431991572", "category_id": "0",
"recurrence_status": "0", "priority": "2",
"recurrence_trigger": "0", "swimlane_id": "0",
"recurrence_factor": "0", "date_moved": "1469315481",
"recurrence_timeframe": "0", "recurrence_status": "0",
"recurrence_basedate": "0", "recurrence_trigger": "0",
"recurrence_parent": null, "recurrence_factor": "0",
"recurrence_child": null, "recurrence_timeframe": "0",
"task_id": "1", "recurrence_basedate": "0",
"changes": { "recurrence_parent": null,
"category_id": "2" "recurrence_child": null,
"category_name": null,
"swimlane_name": null,
"project_name": "Demo Project",
"default_swimlane": "Default swimlane",
"column_title": "Ready",
"assignee_username": "admin",
"assignee_name": null,
"creator_username": "admin",
"creator_name": null
},
"changes": {
"description": "New description",
"color_id": "purple",
"date_due": 1469836800
}
} }
}
} }
``` ```
Task update events have a field called `changes` that contains updated values. Task update events have a field called `changes` that contains updated values.
Move a task to another column:
```json
{
"event_name": "task.move.column",
"event_data": {
"task_id": "1",
"project_id": "1",
"position": 1,
"column_id": "1",
"swimlane_id": "0",
"src_column_id": "2",
"dst_column_id": "1",
"date_moved": "1431991532",
"recurrence_status": "0",
"recurrence_trigger": "0"
}
}
```
Move a task to another position:
```json
{
"event_name": "task.move.position",
"event_data": {
"task_id": "2",
"project_id": "1",
"position": 1,
"column_id": "1",
"swimlane_id": "0",
"src_column_id": "1",
"dst_column_id": "1",
"date_moved": "1431996905",
"recurrence_status": "0",
"recurrence_trigger": "0"
}
}
```
Comment creation: Comment creation:
```json ```json
{ {
"event_name": "comment.create", "event_name": "comment.create",
"event_data": { "event_data": {
"id": 1, "comment": {
"task_id": "1", "id": "1",
"user_id": "1", "task_id": "5",
"comment": "test", "user_id": "1",
"date_creation": 1431991615 "date_creation": "1469315727",
} "comment": "My comment.",
} "reference": null,
``` "username": "admin",
"name": null,
Comment modification: "email": null,
"avatar_path": null
``` },
{ "task": {
"event_name": "comment.update", "id": "5",
"event_data": { "reference": "",
"id": "1", "title": "My new task",
"task_id": "1", "description": "New description",
"user_id": "1", "date_creation": "1469315481",
"comment": "test edit" "date_completed": null,
} "date_modification": "1469315531",
"date_due": "1469836800",
"date_started": "0",
"time_estimated": "0",
"time_spent": "0",
"color_id": "purple",
"project_id": "1",
"column_id": "2",
"owner_id": "1",
"creator_id": "1",
"position": "1",
"is_active": "1",
"score": "3",
"category_id": "0",
"priority": "2",
"swimlane_id": "0",
"date_moved": "1469315481",
"recurrence_status": "0",
"recurrence_trigger": "0",
"recurrence_factor": "0",
"recurrence_timeframe": "0",
"recurrence_basedate": "0",
"recurrence_parent": null,
"recurrence_child": null,
"category_name": null,
"swimlane_name": null,
"project_name": "Demo Project",
"default_swimlane": "Default swimlane",
"column_title": "Ready",
"assignee_username": "admin",
"assignee_name": null,
"creator_username": "admin",
"creator_name": null
}
}
} }
``` ```
@@ -221,28 +304,65 @@ Subtask creation:
```json ```json
{ {
"event_name": "subtask.create", "event_name": "subtask.create",
"event_data": { "event_data": {
"id": 3, "subtask": {
"task_id": "1", "id": "1",
"title": "Test", "title": "My subtask",
"user_id": "1", "status": "0",
"time_estimated": "2", "time_estimated": "0",
"position": 3 "time_spent": "0",
} "task_id": "5",
} "user_id": "1",
``` "position": "1",
"username": "admin",
Subtask modification: "name": null,
"timer_start_date": 0,
```json "status_name": "Todo",
{ "is_timer_started": false
"event_name": "subtask.update", },
"event_data": { "task": {
"id": "1", "id": "5",
"status": 1, "reference": "",
"task_id": "1" "title": "My new task",
} "description": "New description",
"date_creation": "1469315481",
"date_completed": null,
"date_modification": "1469315531",
"date_due": "1469836800",
"date_started": "0",
"time_estimated": "0",
"time_spent": "0",
"color_id": "purple",
"project_id": "1",
"column_id": "2",
"owner_id": "1",
"creator_id": "1",
"position": "1",
"is_active": "1",
"score": "3",
"category_id": "0",
"priority": "2",
"swimlane_id": "0",
"date_moved": "1469315481",
"recurrence_status": "0",
"recurrence_trigger": "0",
"recurrence_factor": "0",
"recurrence_timeframe": "0",
"recurrence_basedate": "0",
"recurrence_parent": null,
"recurrence_child": null,
"category_name": null,
"swimlane_name": null,
"project_name": "Demo Project",
"default_swimlane": "Default swimlane",
"column_title": "Ready",
"assignee_username": "admin",
"assignee_name": null,
"creator_username": "admin",
"creator_name": null
}
}
} }
``` ```
@@ -250,22 +370,118 @@ File upload:
```json ```json
{ {
"event_name": "file.create", "event_name": "task.file.create",
"event_data": { "event_data": {
"task_id": "1", "file": {
"name": "test.png" "id": "1",
} "name": "kanboard-latest.zip",
"path": "tasks/5/6f32893e467e76671965b1ec58c06a2440823752",
"is_image": "0",
"task_id": "5",
"date": "1469315613",
"user_id": "1",
"size": "4907308"
},
"task": {
"id": "5",
"reference": "",
"title": "My new task",
"description": "New description",
"date_creation": "1469315481",
"date_completed": null,
"date_modification": "1469315531",
"date_due": "1469836800",
"date_started": "0",
"time_estimated": "0",
"time_spent": "0",
"color_id": "purple",
"project_id": "1",
"column_id": "2",
"owner_id": "1",
"creator_id": "1",
"position": "1",
"is_active": "1",
"score": "3",
"category_id": "0",
"priority": "2",
"swimlane_id": "0",
"date_moved": "1469315481",
"recurrence_status": "0",
"recurrence_trigger": "0",
"recurrence_factor": "0",
"recurrence_timeframe": "0",
"recurrence_basedate": "0",
"recurrence_parent": null,
"recurrence_child": null,
"category_name": null,
"swimlane_name": null,
"project_name": "Demo Project",
"default_swimlane": "Default swimlane",
"column_title": "Ready",
"assignee_username": "admin",
"assignee_name": null,
"creator_username": "admin",
"creator_name": null
}
}
} }
``` ```
Screenshot created: Task link creation:
```json ```json
{ {
"event_name": "file.create", "event_name": "task_internal_link.create_update",
"event_data": { "event_data": {
"task_id": "2", "task_link": {
"name": "Screenshot taken May 19, 2015 at 10:56 AM" "id": "2",
} "opposite_task_id": "5",
"task_id": "4",
"link_id": "3",
"label": "is blocked by",
"opposite_link_id": "2"
},
"task": {
"id": "4",
"reference": "",
"title": "My task",
"description": "",
"date_creation": "1469314356",
"date_completed": null,
"date_modification": "1469315422",
"date_due": "1469491200",
"date_started": "0",
"time_estimated": "0",
"time_spent": "0",
"color_id": "green",
"project_id": "1",
"column_id": "1",
"owner_id": "1",
"creator_id": "1",
"position": "1",
"is_active": "1",
"score": "0",
"category_id": "0",
"priority": "0",
"swimlane_id": "0",
"date_moved": "1469315422",
"recurrence_status": "0",
"recurrence_trigger": "0",
"recurrence_factor": "0",
"recurrence_timeframe": "0",
"recurrence_basedate": "0",
"recurrence_parent": null,
"recurrence_child": null,
"category_name": null,
"swimlane_name": null,
"project_name": "Demo Project",
"default_swimlane": "Default swimlane",
"column_title": "Backlog",
"assignee_username": "admin",
"assignee_name": null,
"creator_username": "admin",
"creator_name": null
}
}
} }
``` ```