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:
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.
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.
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 and subprojects 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 and subprojects 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 created under the API app associated with the token used for request authorization.
[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": "IEAAABC6JAAAABAS",
"eventAuthorId": "KUAAABKU",
"eventType": "TaskCreated",
"taskId": "IEAAABC6KQAB5FKW",
"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": "IEAAABC6KQAB5FKW",
"webhookId": "IEAAABC6JAAAABAS",
"eventAuthorId": "KUAAABKU",
"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": "IEAAABC6KQAB5FKW",
"webhookId": "IEAAABC6JAAAABAS",
"eventAuthorId": "KUAALDRX",
"eventType": "TaskStatusChanged",
"lastUpdatedDate": "2016-11-22T11:09:58Z"
}
Note that custom field values are represented in the form of JSON string, so when custom field has text type, it will be wrapped in quotes:
{
"customFieldId": "IEAAABDGJUAAAAA6",
"oldValue": "\"old text\"",
"value": "\"new value\"",
"taskId": "IEAAABDGKQAB5FLY",
"webhookId": "IEAAABDGJAAAABA2",
"eventAuthorId": "KUAAABLA",
"eventType": "TaskCustomFieldChanged",
"lastUpdatedDate": "2024-09-05T07:33:24Z"
}
For events related to task child entities, (that is, attachments), payload will contain corresponding entity ID. Example is AttachmentAdded event:
{
"webhookId": "IEAAABC6JAAAABAS",
"eventAuthorId": "KUAALDRX",
"eventType": "AttachmentAdded",
"lastUpdatedDate": "2016-10-10T11:33:28Z",
"taskId": "IEAAABC6KQAB5FKW",
"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. It's also fired for creating task-based work items and submitting request forms.
| |
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, project or space
| |
TaskParentsRemoved | Fired when a task is removed from a folder, project or space
| |
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 or a comment with attachment is added
| |
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
| |
CreateFromBlueprintCompleted | Fired when a creation from blueprint of task/project/folder is completed
| |
TimelogChanged | Fired when a timelog record is added, updated, or removed
| |
FolderCreated | Fired when a folder, project or space is created. It's also fired for creating folder or project-based work items.
| |
FolderDeleted | Fired when a folder, project or space is deleted
| |
FolderTitleChanged | Fired when a user changes the title of a folder, project or space
| |
FolderParentsAdded | Fired when a folder or project is added to another folder, project or space
| |
FolderParentsRemoved | Fired when a folder or project is removed from another folder
| |
FolderSharedsAdded | Fired when a folder, project or space is shared
| |
FolderSharedsRemoved | Fired when a folder, project or space 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
| |
TaskApprovalStatusChanged | Fired when a task's approval status is changed
| |
TaskApprovalDecisionChanged | Fired when a user gives his decision on approval for task
| |
TaskApprovalDecisionReset | Fired when a user's actions reset a previous decision for task. For example, if a task's files have been tejected and the approval tejected, when a user uploads a new version of a file the approval decision is reset, and this event is triggered.
| |
FolderApprovalStatusChanged | Fired when a folder's or project's approval status is changed
| |
FolderApprovalDecisionChanged | Fired when a folder's or project's approval final decision is changed
| |
FolderApprovalDecisionReset | Fired when a user's actions reset a previous decision for folder or project. For example, if a folder's files have been rejected and the approval rejected, when a user uploads a new version of an approval file the approval decision is reset, and this event is triggered.
| |
WorkItemTypeChanged | Fired when a user changes the type of a work item, e.g., when an ordinary Task is converted to a particular Custom Item Type.
| |
ImportFromFileCompleted | Fired when import from Excel or Microsoft Project file is completed
|
The following events are not yet supported (and do not trigger notifications):
Changes made with mass actions, including importing tasks
Webhook URL Requirements
Current requirements for hookUrl are following:
Web protocol must be present in the URL and must be either http or https, other protocols are not supported (and will not be)
Address must be global, not an intranet address (https://en.wikipedia.org/wiki/Private_network)
Port (if specified) must be either 80 or 443
If an incorrect port is used, you will receive a generic error message as follows:
{
"errorDescription":"Parameter 'hookUrl' value is invalid",
"error":"invalid_parameter"
}
Examples of Valid hookUrls:
hookUrl=https://[Global_IP_address]:80/receiver
hookUrl=https://[Global_IP_address]:433/receiver
Verifying the Accessibility of the Hook URL
To validate the accessibility of a hook URL, send a POST request to the URL.
POST https://webhook.site/7fbe2965-3d60-4d11-ac6d-f5c792ac1723
Successful connectivity is indicated by one of the following HTTP status codes in the response:
200 OK
201 Created
202 Accepted
204 No Content
Webhooks delivery
To ensure proper webhooks delivery from Wrike, whitelist following IP subnets:
For US DC: 160.19.162.0/23, 34.73.3.211/32
For US2 DC: 35.196.104.95/32, 34.72.158.28/32
For EU DC: 185.157.64.0/22, 146.148.2.222/32
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:
In order to register a secure webhook, send secret parameter:
https://www.wrike.com/api/v4/webhooks?hookUrl=<url>&secret=<some_secret>.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"}.
Client should calculate hmacSha256(key: secret, value: received X-Hook-Secret value) and add calculated value to the response X-Hook-Secret header.
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 a webhook is suspended, Wrike sends an email notification to the webhook author. If your endpoint is shut down or not accessible via the internet, we automatically suspend the webhook based on the response status. In this case, the following request using the given webhook ID will return the “Suspended” state for the 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"
}
]
}
Retries for Webhooks
For retryable HTTP statuses, we attempt delivering up to 3 times. If all attempts fail, the webhook is suspended. However, for non-retryable HTTP statuses - all 4xx status codes, except for 408 and 429 - the webhook gets suspended immediately with no retries.
Additionally, if endpoints continue to fail and retries prove ineffective, the system will temporarily suspend all retries to prevent unnecessary delays.
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"
}
]
}
Handling duplicate deliveries
We cannot guarantee exactly-once delivery of events via webhooks. It is possible that due to network issues, the same payload may be re-delivered to your handler. You can prevent the processing of such duplicate deliveries by using an Idempotency-Key header in the request. The Idempotency-Key contains a unique identifier for each event, allowing you to determine if the event has already been processed.