Update webhooks documentation

This commit is contained in:
Frederic Guillot 2016-07-23 19:21:32 -04:00
parent ca45b5592b
commit 8e6e335c9d
No known key found for this signature in database
GPG Key ID: 92D77191BA7FBC99
2 changed files with 401 additions and 244 deletions

View File

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

View File

@ -1,5 +1,5 @@
Web Hooks
=========
Webhooks
========
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.update
- comment.delete
- file.create
- task.move.project
- task.move.column
@ -33,6 +34,9 @@ All internal events of Kanboard can be sent to an external URL.
- task.assignee_change
- subtask.update
- subtask.create
- subtask.delete
- task_internal_link.create_update
- task_internal_link.delete
### Example of HTTP request
@ -43,19 +47,65 @@ Content-Type: application/json
Connection: close
{
"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"
}
"event_name": "task.move.column",
"event_data": {
"task_id": "4",
"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
},
"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
{
"event_name": "task.create",
"event_data": {
"title": "Demo",
"description": "",
"project_id": "1",
"owner_id": "1",
"category_id": 0,
"swimlane_id": 0,
"column_id": "2",
"color_id": "yellow",
"score": 0,
"time_estimated": 0,
"date_due": 0,
"creator_id": 1,
"date_creation": 1431991532,
"date_modification": 1431991532,
"date_moved": 1431991532,
"position": 1,
"task_id": 1
}
"event_name": "task.create",
"event_data": {
"task_id": 5,
"task": {
"id": "5",
"reference": "",
"title": "My new task",
"description": "",
"date_creation": "1469315481",
"date_completed": null,
"date_modification": "1469315481",
"date_due": "0",
"date_started": "0",
"time_estimated": "0",
"time_spent": "0",
"color_id": "orange",
"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
}
}
}
```
@ -107,113 +182,121 @@ Task modification:
```json
{
"event_name": "task.update",
"event_data": {
"id": "1",
"title": "Demo",
"description": "",
"date_creation": "1431991532",
"color_id": "yellow",
"project_id": "1",
"column_id": "1",
"owner_id": "1",
"position": "1",
"is_active": "1",
"date_completed": null,
"score": "0",
"date_due": "0",
"category_id": "2",
"creator_id": "1",
"date_modification": 1431991603,
"reference": "",
"date_started": 1431993600,
"time_spent": 0,
"time_estimated": 0,
"swimlane_id": "0",
"date_moved": "1431991572",
"recurrence_status": "0",
"recurrence_trigger": "0",
"recurrence_factor": "0",
"recurrence_timeframe": "0",
"recurrence_basedate": "0",
"recurrence_parent": null,
"recurrence_child": null,
"task_id": "1",
"changes": {
"category_id": "2"
"event_name": "task.update",
"event_data": {
"task_id": "5",
"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
},
"changes": {
"description": "New description",
"color_id": "purple",
"date_due": 1469836800
}
}
}
}
```
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:
```json
{
"event_name": "comment.create",
"event_data": {
"id": 1,
"task_id": "1",
"user_id": "1",
"comment": "test",
"date_creation": 1431991615
}
}
```
Comment modification:
```
{
"event_name": "comment.update",
"event_data": {
"id": "1",
"task_id": "1",
"user_id": "1",
"comment": "test edit"
}
"event_name": "comment.create",
"event_data": {
"comment": {
"id": "1",
"task_id": "5",
"user_id": "1",
"date_creation": "1469315727",
"comment": "My comment.",
"reference": null,
"username": "admin",
"name": null,
"email": null,
"avatar_path": null
},
"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
}
}
}
```
@ -221,28 +304,65 @@ Subtask creation:
```json
{
"event_name": "subtask.create",
"event_data": {
"id": 3,
"task_id": "1",
"title": "Test",
"user_id": "1",
"time_estimated": "2",
"position": 3
}
}
```
Subtask modification:
```json
{
"event_name": "subtask.update",
"event_data": {
"id": "1",
"status": 1,
"task_id": "1"
}
"event_name": "subtask.create",
"event_data": {
"subtask": {
"id": "1",
"title": "My subtask",
"status": "0",
"time_estimated": "0",
"time_spent": "0",
"task_id": "5",
"user_id": "1",
"position": "1",
"username": "admin",
"name": null,
"timer_start_date": 0,
"status_name": "Todo",
"is_timer_started": false
},
"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
}
}
}
```
@ -250,22 +370,118 @@ File upload:
```json
{
"event_name": "file.create",
"event_data": {
"task_id": "1",
"name": "test.png"
}
"event_name": "task.file.create",
"event_data": {
"file": {
"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
{
"event_name": "file.create",
"event_data": {
"task_id": "2",
"name": "Screenshot taken May 19, 2015 at 10:56 AM"
}
"event_name": "task_internal_link.create_update",
"event_data": {
"task_link": {
"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
}
}
}
```