From 8e6e335c9d99ff710ecd70dff293f15a25bf9a98 Mon Sep 17 00:00:00 2001 From: Frederic Guillot Date: Sat, 23 Jul 2016 19:21:32 -0400 Subject: Update webhooks documentation --- doc/ru_RU/webhooks.markdown | 99 ++------ doc/webhooks.markdown | 546 +++++++++++++++++++++++++++++++------------- 2 files changed, 401 insertions(+), 244 deletions(-) (limited to 'doc') diff --git a/doc/ru_RU/webhooks.markdown b/doc/ru_RU/webhooks.markdown index c598abf9..dbba0867 100644 --- a/doc/ru_RU/webhooks.markdown +++ b/doc/ru_RU/webhooks.markdown @@ -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 diff --git a/doc/webhooks.markdown b/doc/webhooks.markdown index 628c7e38..e43ab9ce 100644 --- a/doc/webhooks.markdown +++ b/doc/webhooks.markdown @@ -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 + } + } } ``` -- cgit v1.2.3