Visit API Community

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 a (“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 changes to any tasks in the Account. Includes changes to all tasks that are shared with you in the account.

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 account.
  • [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": "Active",
    "status": "Completed",
    "taskId": "IEAADQQLKQAKOFAB",
    "webhookId": "IEAADQQLJAAAAULL",
    "eventAuthorId": "KUAALDRX"
    "eventType": "TaskStatusChanged"
    "lastUpdatedDate": "2016-11-22T11:09:58Z"
}

Task statuses mentioned in “oldStatus” and “status” fields are described for “status” parameter of “query-tasks” API method.

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.

Event Description Old Value
TaskCreated Fired when a user creates a new task
TaskDeleted Fired when task is deleted
TaskTitleChanged Fired when a task title changes
TaskImportanceChanged Fired when a task importance changes
TaskStatusChanged Fired when a task status changes
TaskDatesChanged Fired when start, finish dates, duration, or the “Work on weekends” flag is changes
TaskParentsAdded Fired when a task is added to a folder
TaskParentsRemoved Fired when a task is removed from a folder
TaskResponsiblesAdded Fired when any new assignee is added to a task, including all Wrike users (and collaborators) and users with pending invitations
TaskResponsiblesRemoved Fired when someone is unassigned from a task
TaskSharedsAdded Fired when a task is shared
TaskSharedsRemoved Fired when a task is unshared
TaskDescriptionChanged Fired when a task’s description is changed. Note: Notifications related to description field changes are fired with approximately a 5-minute delay.
TaskCustomFieldChanged Fired when a custom field value on a custom field is changed
AttachmentAdded Fired when a new attachment is added to a task
AttachmentDeleted Fired when an attachment was deleted from task or a comment with attachment was deleted
CommentAdded Fired when a new comment is added. Not fired for comments without text (that is, comments with attachments only).
CommentDeleted Fired when a comment is deleted
TimelogChanged Fired when a timelog record is added, updated, or removed
FolderCreated Fired when a folder or project is created
FolderDeleted Fired when a folder or project is deleted
FolderTitleChanged Fired when a user changes the title of a folder or project
FolderParentsAdded Fired when a folder or project is added to another folder
FolderParentsRemoved Fired when a folder or project is removed from another folder
FolderSharedsAdded Fired when a folder or project is shared
FolderSharedsRemoved Fired when a folder or project is unshared
FolderDescriptionChanged Fired when a user changes the description of a folder or project
FolderCommentAdded Fired when a comment is added to a folder or project
FolderCommentDeleted Fired when a comment is removed from a folder or project
FolderAttachmentAdded Fired when an attachment is added to a folder or project
FolderAttachmentDeleted Fired when an attachment is removed from a folder or project
FolderCustomFieldChanged Fired when a custom field value is changed for folder or project
ProjectDatesChanged Fired when the start or end dates of a project are changed
ProjectOwnersAdded Fired when any new owner is assigned to a project, including all Wrike users (and Collaborators) and users with pending invitations
ProjectOwnersRemoved Fired when an owner is unassigned from a project
ProjectStatusChanged

Fired when a project status changes

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

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, as described on this page. 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. Upon webhook registration, client sends 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.
  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 POST -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",
        }
    ]
}