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. 

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.

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” 

​

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: 

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

https://youraccount.worksection.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://youraccount.worksection.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": "paused"
        }
    ]
}​

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

https://youraccount.worksection.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://youraccount.worksection.com/api/oauth2?action=add_webhook&
url=<url>&events=<events>&http_user=<http_user>&http_pass=<http_pass>

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"
}​​​

The delete_webhooks method can be executed using the admin API key: 

https://youraccount.worksection.com/api/admin/v2/?action=delete_webhook&
id=<id>&hash=HASH

or using an OAuth 2.0 token with scope = administrative:

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

Example response:

{
    "status": "ok"
}