WORKSECTION

Webhooks

How webhooks works

Webhooks are a useful tool that allows you to receive notifications of changes in Worksection without the need for constant API requests.

 When certain changes occur in your account, a small data packet is automatically sent to the HTTP destination you specify. Webhooks notify you of account events, not the user. You can also subscribe to different types of events and specify the projects you're interested in receiving changes. 

Was this article helpful? Yes, thank you! No

Create a webhook

To cre­ate a web­hook, go to the API sec­tion of your Аccount settings. 

In the Web­hooks field, click Cre­ate.


  1. Enter the URL that will accept web­hook requests. 
    It must return the fol­low­ing http response: (HTTP sta­tus: 200, Head­er: JSON, Body: {“sta­tus”: OK”}) for any request with­in 5 sec­onds, oth­er­wise the request will be treat­ed as an error.
  2. Select the events that will send requests to the spec­i­fied URL.
  3. Select projects for which events will be sent. By default, events will be sent for all projects.
  4. If nec­es­sary, spec­i­fy http user, http pass­word to con­nect via basic access authentication.
  5. Check the valid­i­ty of your URL by click­ing the Test but­ton. 


Click the Cre­ate but­ton to confirm.

Was this article helpful? Yes, thank you! No

Additional webhook settings

By default, the cre­at­ed web­hook will be dis­abled. When you need it, enable it manually:


If the spec­i­fied URL is invalid, an error will appear when you enable it:  



If nec­es­sary, you can dis­able and delete the web­hook. 



Web­hooks can be in three sta­tus­es:  
  • Gray — Dis­abled”
  • Green — Work­ing”
  • Orange — Work­ing, but has failed attempts” 

If 10 errors occur, the web­hook will be auto­mat­i­cal­ly disabled.

Was this article helpful? Yes, thank you! No

Types of webhook events

EVENTDESCRIP­TION
Cre­ate a taskLaunched when a user cre­ates a new task
Edit­ing a taskLaunched when a task is edited
Task com­ple­tionLaunched when a task changes its sta­tus to com­plet­ed
Delete a taskLaunched when a task is deleted
Cre­ate a commentLaunched when a user cre­ates a new comment
Edit a commentLaunched when a com­ment is edited
Delete a commentLaunched when a com­ment is deleted
Delete a commentLaunched when a user cre­ates a new project
Edit a projectLaunched when a project is edited
Was this article helpful? Yes, thank you! No

Example of using a webhook

An enabled web­hook looks like this: 


When you cre­ate a project, the fol­low­ing event will be sent to the spec­i­fied URL: 

Was this article helpful? Yes, thank you! No

Creating a webhook via API: add_webhook

The add_webhook method can be executed using the administrative API key: 

https://your—domain.com/api/admin/v2/?action=add_webhook&
url=<url>&events=<events>&http_user=<http_user>&http_pass=<http_pass>hash=HASH

or using an OAuth 2.0 token with scope = administrative:

curl -X GET -H "Authorization: Bearer <token_value>"
https://your-domain.com/api/oauth2?action=add_webhook&url=<url>&events=<events>&http_user=<http_user>&http_pass=<http_pass>

PARAMETERDESCRIPTION
url
URL of the webhook to which events will be sent. The URL should return a response in the format (HTTP status: 200, Header: json, Body: {"status": "OK"})
events
The event settings that will send notifications to the specified URL are separated by commas. Possible values: post_task, post_comment, post_project, update_task, update_comment, update_project, delete_task, delete_comment, close_task
http_user
Optional parameter - user when using basic access authentication
http_pass
Optional parameter - password when using basic access authentication
projects
Optional parameter - project IDs separated by commas, specify if you want to limit the sending of events for certain projects

Example of a successful response:

{
    "status": "ok",
    "id": 16
}

Example of an unsuccessful response:

{
    "status": "error",
    "status_code": 11,
    "message": "Url should respond 200 HTTP_CODE and JSON {status:OK}",
    "message_details": "https://google.com"
}​​
Was this article helpful? Yes, thank you! No

Getting webhooks via API: get_webhooks

The get_webhooks method can be executed using the administrative API key: 

https://your—domain.com/api/admin/v2/?action=get_webhooks&hash=HASH

or using an OAuth 2.0 token with scope = administrative:

curl -X GET -H "Authorization: Bearer <token_value>"
https://your—domain.com/api/oauth2?action=get_webhooks

Example response:

{
    "status": "ok",
    "data": [
        {
            "id": "14",
            "url": "https://eoaerzysr8s23hq.m.pipedream.net",
            "events": "post_task,delete_task,reopen_task",
            "status": "active",
            "projects": "333"
        },
        {
            "id": "16",
            "url": "https://eolb4pffb2s43u.m.pipedream.net",
            "events": "post_task,post_comment,post_project",
            "status": "active"
        }
    ]
}​
Was this article helpful? Yes, thank you! No

Delete a webhook using the API: delete_webhook

The get_webhooks method can be executed using the admin API key

https://your—domain.com/api/admin/v2/?action=delete_webhook&id=<id>&hash=HASH

or using an OAuth 2.0 token with = administrative:

curl -X GET -H "Authorization: Bearer <token_value>"
https://your—domain.com/api/oauth2?action=delete_webhookd&id=<id>

Example response:

{
    "status": "ok"
}
Was this article helpful? Yes, thank you! No
esc
или
Print