Webhooks

Webhooks allow you to subscribe to notifications about changes in Wrike instead of having to rely on periodic polling. When webhooks are in place, a small package of information (“payload”) is sent to your HTTP endpoint when specific changes occur.

We support the following scopes for webhooks:

1. Folder webhooks - Fire notifications about changes to tasks within a single folder or project. You can subscribe to folder/project individually, or use “recursive” webhooks to subscribe to folder/project and its subfolders/subprojects.

2. Account webhooks - Fire notifications about task, folder, and project-related events in the Account. Includes changes to all tasks that are shared with you in the account.

3. Space webhooks - Fire notifications about changes to tasks, folders, and projects within a single space.
   

API Methods

REST-style API methods allow you to create webhooks, get lists of your webhooks and their states, update webhook states, and delete webhooks.

Create Webhooks

• [POST] /folders/{folderId}/webhooks — Creates a webhook for a target folder/project.

  Parameters:

  • hookUrl - URL of the server that will receive the payload.

  • secret (optional) - Client secret to check authenticity of the events later. See Secure Webhooks section below.

  • events (optional) - Comma-separated list of events that client wants to subscribe to, in square brackets.

    Example: [AttachmentAdded,AttachmentDeleted]. If not specified, all events will be received. See supported events here.

  • recursive (optional) - Specifies whether hook should listen to events for subfolders or tasks anywhere in the hierarchy. Default value is false, set to true for tracking all nested elements.

• [POST] /spaces/{spaceId}/webhooks — Creates a webhook for a target space.

  Parameters:

  • hookUrl - URL of the server that will receive the payload.

  • secret (optional) - Client secret to check authenticity of the events later. See Secure Webhooks section below.

  • events (optional) - Comma-separated list of events that client wants to subscribe to, in square brackets.

    Example: [AttachmentAdded,AttachmentDeleted]. If not specified, all events will be received. See supported events here.

  • recursive (optional) - Specifies whether hook should listen to events for subfolders or tasks anywhere in the hierarchy. Default value is false, set to true for tracking all nested elements.

• [POST] /webhooks — Creates a webhook for a current account.

  Parameters:

  • hookUrl - URL of the server that will receive the payload.

  • secret (optional) - Client secret to check authenticity of the events later. See Secure Webhooks section below.

  • events (optional) - Comma-separated list of events that client wants to subscribe to, in square brackets.

    Example: [AttachmentAdded,AttachmentDeleted]. If not specified, all events will be received. See supported events here.

Get Webhook(s) State

• [GET] /webhooks — Returns a list of webhooks for current token.

• [GET] /webhooks/{webhookId},{webhookId},... [up to 100 IDs] — Returns information for the specified webhooks.

• The response model for these methods includes the following data for each hook: 
  webhook ID, account ID, Folder ID (optional), your server's URL and status (Active | Suspended).

Update Webhook State

• [PUT] /webhooks/{webhookId} — Modifies the webhooks state to suspend or resume. Suspended webhooks do not send notifications.

  Parameters:

  • status = Active | Suspended

Delete Webhooks

• [DELETE] /webhooks/{webhookId} — Deletes webhook by ID.

Sample Payloads

Below is an example of the most basic payload which can be received. This payload is sent when a new task is created (note the “eventType”):

[{
    "webhookId": "IEAADQQLKQAKAOPB",
    "eventAuthorId": "KQAKAOPB",
    "eventType": "TaskCreated",
    "taskId": "IEAADQQLKQAKAOPB",
    "lastUpdatedDate": "2016-10-10T11:33:28Z"
}]

Note, even single notifications are sent as JSON-array. For simplicity, we’ll write payloads as single JSON-objects in the text below.

Some payloads can contain values that designate what the data was before the change. For example, for the TaskTitleChanged event you see the old and new task title:

{
    "oldValue": "Old task title",
    "title": "New task title",
    "taskId": "IEAADQQLKQAKOFAB",
    "webhookId": "IEAADQQLJAAAAULL",
    "eventAuthorId": "KUAALDRX",
    "eventType": "TaskTitleChanged",
    "lastUpdatedDate": "2016-11-22T10:25:50Z"
}

Another example with old/new values is TaskStatusChanged:

{
    "oldStatus": "New",
    "status": "In Progress",
    "oldCustomStatusId": "IEAADQQLJMAAAAAA",
    "customStatusId": "IEAADQQLJMA7IM7A",
    "taskId": "IEAADQQLKQAKOFAB",
    "webhookId": "IEAADQQLJAAAAULL",
    "eventAuthorId": "KUAALDRX",
    "eventType": "TaskStatusChanged",
    "lastUpdatedDate": "2016-11-22T11:09:58Z"
}

For events related to task child entities, (that is, attachments), payload will contain corresponding entity ID. Example is AttachmentAdded event:

{
    "webhookId": "IEAADQQLJAAAAULL",
    "eventAuthorId": "KUAALDRX",
    "eventType": "AttachmentAdded",
    "lastUpdatedDate": "2016-10-10T11:33:28Z",
    "taskId": "IEAADQQLKQAKAOPB",
    "attachmentId": "IEAADQQLKQAKAOPD"
}

To get detailed information about the attachment, use the Get Attachments method with the ID you'd received.

Event Types

The following table lists supported webhooks events. Events on tasks, folders, projects, attachments, timelogs, and comments changes are supported. Folder events are also fired on projects.

{
    "oldStatus": "In Progress",
    "status": "Completed",
    "oldCustomStatusId": "IEABPELHJMAMIUZO",
    "customStatusId": "IEABPELHJMAMIUZF",
    "taskId": "IEABPELHI4AQE2MM",
    "webhookId": "IEABPELHJAAABATM",
    "eventAuthorId": "KUGEUT27",
    "eventType": "ProjectStatusChanged",
    "lastUpdatedDate": "2019-06-17T11:42:28Z"
}

[
 {
  "approvalId": "IEADGRKWMEAD3QBO",
  "status": "Approved",
  "webhookId": "IEADGRKWJAAAY2DH",
  "eventAuthorId": "KUAG52VT",
  "eventType": "FolderApprovalDecisionChanged",
  "lastUpdatedDate": "2021-03-03T14:21:04Z"
 }
]

[
 {
  "approvalId": "IEADGRKWMEAD3QBO",
  "decision": "Approved",
  "webhookId": "IEADGRKWJAAAY2DH",
  "eventAuthorId": "KUAG52VT",
  "eventType": "FolderApprovalDecisionChanged",
  "lastUpdatedDate": "2021-03-03T14:21:04Z"
 }
]

The following events are not yet supported (and do not trigger notifications):

• Changes made with mass actions, including importing tasks

Secure Webhooks

Wrike optionally supports signing event payloads with a secret, pre-shared between client and Wrike. This provides a mechanism to check authenticity of the request and make sure it is indeed coming from Wrike and goes to the client who registered it.

The general flow looks like follows:

1. In order to register a secure webhook, send secret parameter: 
   https://www.wrike.com/api/v4/webhooks?hookUrl=<url>&secret=<some_secret>.

2. Wrike sends request to hookUrl with header X-Hook-Secret, which contains random alphanumeric string. This request will also have the following body - {"requestType": "WebHook secret verification"}.

3. Client should calculate hmacSha256(key: secret, value: received X-Hook-Secret value) and add calculated value to the response X-Hook-Secret header.

4. All events from webhook will contain X-Hook-Secret header with value hmacSha256(key: secret, value: request body) so client can check authenticity of the events.

Example of Usage

Use Case Example

Let’s assume a task is related to the development process, and a “Completed” status means that all code was committed/pushed to the source repository. This change could trigger a CI build via some CI REST endpoint.

Step 1

Create an account-wide webhook.

Get your accountId using the following CURL command:

curl -g -X GET -H 'Authorization: bearer <access_token>' 'https://www.wrike.com/api/v4/account'

The response contains a list of your accounts:

{
    "kind": "accounts",
    "data": [
        {
        "id": "IEAADQQL",
        "name": "My Personal Account",
        "dateFormat": "MM/dd/yyyy",
        "firstDayOfWeek": "Mon",
        "workDays": [
            "Sun",
            "Mon",
            "Tue",
            "Wed",
            "Thu",
            "Fri",
            "Sat"
        ],
        "rootFolderId": "IEAAAOVII7777777",
        "recycleBinId": "IEAAAOVII7777776",
        "createdDate": "2013-12-30T12:17:24Z",
        "joinedDate": "2015-08-04T13:56:13Z"
        }
    ]
}

You will need “id” field for future requests (“IEAADQQL” in the example above).

Step 2

Execute the following CURL command to create a new account-wide webhook and subscribe your endpoint (https://yourwebhookserver.com/event-handler) to notifications.

Get your accountId using the following CURL command:

curl -g -X POST -H 'Authorization: bearer <access_token>' -d 'hookUrl=https://yourwebhookserver.com/event-handler' 'https://www.wrike.com/api/v4/webhooks'

You’ll see the following response:

{
    "kind": "webhooks",
    "data": [
        {
        "id": "IEAADQQLJAAAAULN",
        "accountId": "IEAADQQL",
        "hookUrl": "https://yourwebhookserver.com/event-handler",
        "status": "Active"
        }
    ]
}

Step 3

Next, change a task in the account (for example, change a task’s status from “Active” to “Completed”). You’ll receive the following payload on your endpoint:

{
    "oldStatus": "Active",
    "status": "Completed",
    "webhookId": "IEAADQQLJAAAAULN",
    "eventAuthorId": "KUAALDRX",
    "eventType": "TaskStatusChanged",
    "lastUpdatedDate": "2016-11-22T11:09:58Z"
}

Suspended Webhooks

If you shut down your endpoint or it is not accessible via the internet, then we automatically suspend the webhook after 3 retries. In this case, the following request by given webhook ID returns the “Suspended” state for webhook:

curl -g -X GET -H 'Authorization: bearer <access_token>' 'https://www.wrike.com/api/v4/webhooks/IEAADQQLJAAAAULN'

Response reflecting “Suspended” state:

{
    "kind": "webhooks",
    "data": [
        {
        "id": "IEAADQQLJAAAAULN",
        "accountId": "IEAADQQL",
        "hookUrl": "https://yourwebhookserver.com/event-handler",
        "status": "Suspended"
        }
    ]
}

Restart Webhooks

Restart the webhook using the following PUT request:

curl -g -X PUT -H 'Authorization: bearer <access_token>' 'https://www.wrike.com/api/v4/webhooks/IEAADQQLJAAAAULN'

Response:

{
    "kind": "webhooks",
    "data": [
        {
        "id": "IEAADQQLJAAAAULN",
        "accountId": "IEAADQQL",
        "hookUrl": "https://yourwebhookserver.com/event-handler",
        "status": "Active"
        }
    ]
}

You can get a list of your webhooks (and their states) at any time:

curl -g -X GET -H 'Authorization: bearer <access_token>' 'https://www.wrike.com/api/v4/webhooks'

Response will contain JSON with all of webhooks created by you. Similar to:

{
    "kind": "webhooks",
    "data": [
        {
        "id": "IEAADQQLJAAAAULN",
        "accountId": "IEAADQQL",
        "hookUrl": "https://yourwebhookserver.com/event-handler",
        "status": "Active"
        }
    ]
}