diff options
Diffstat (limited to 'doc/webhooks.markdown')
| -rw-r--r-- | doc/webhooks.markdown | 271 |
1 files changed, 0 insertions, 271 deletions
diff --git a/doc/webhooks.markdown b/doc/webhooks.markdown deleted file mode 100644 index 628c7e38..00000000 --- a/doc/webhooks.markdown +++ /dev/null @@ -1,271 +0,0 @@ -Web Hooks -========= - -Webhooks are useful to perform actions with external applications. - -- Webhooks can be used to create a task by calling a simple URL (You can also do that with the API) -- An external URL can be called automatically when an event occurs in Kanboard (task creation, comment updated, etc) - -How to write a web hook receiver? ---------------------------------- - -All internal events of Kanboard can be sent to an external URL. - -- The web hook URL has to be defined in **Settings > Webhooks > Webhook URL**. -- When an event is triggered Kanboard calls the pre-defined URL automatically -- The data are encoded in JSON format and sent with a POST HTTP request -- The web hook token is also sent as a query string parameter, so you can check if the request really comes from Kanboard. -- **Your custom URL must answer in less than 1 second**, those requests are synchronous (PHP limitation) and that can slow down the user interface if your script is too slow! - -### 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 - -### Example of HTTP request - -``` -POST https://your_webhook_url/?token=WEBHOOK_TOKEN_HERE -User-Agent: Kanboard Webhook -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" - } -} -``` - -All event payloads are in the following format: - -```json -{ - "event_name": "model.event_name", - "event_data": { - "key1": "value1", - "key2": "value2", - ... - } -} -``` - -The `event_data` values are not necessary normalized across events. - -### Examples of event payloads - -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 - } -} -``` - -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" - } - } -} -``` - -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" - } -} -``` - -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" - } -} -``` - -File upload: - -```json -{ - "event_name": "file.create", - "event_data": { - "task_id": "1", - "name": "test.png" - } -} -``` - -Screenshot created: - -```json -{ - "event_name": "file.create", - "event_data": { - "task_id": "2", - "name": "Screenshot taken May 19, 2015 at 10:56 AM" - } -} -``` |