diff options
Diffstat (limited to 'doc/webhooks.markdown')
| -rw-r--r-- | doc/webhooks.markdown | 487 |
1 files changed, 0 insertions, 487 deletions
diff --git a/doc/webhooks.markdown b/doc/webhooks.markdown deleted file mode 100644 index e43ab9ce..00000000 --- a/doc/webhooks.markdown +++ /dev/null @@ -1,487 +0,0 @@ -Webhooks -======== - -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 -- 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 - -### 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": "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" - } -} -``` - -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": { - "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 - } - } -} -``` - -Task modification: - -```json -{ - "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. - -Comment creation: - -```json -{ - "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 - } - } -} -``` - -Subtask creation: - -```json -{ - "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 - } - } -} -``` - -File upload: - -```json -{ - "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 - } - } -} -``` - -Task link creation: - -```json -{ - "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 - } - } -} -``` |