Establish a webhook

POST

/webhooks

Webhooks

Establishing a webhook is a two-part process. First, a simple HTTP POST
request initiates the creation similar to creating any other resource.

Next, in the middle of this request comes the confirmation handshake.
When a webhook is created, we will send a test POST to the target with an
X-Hook-Secret header. The target must respond with a 200 OK or

204
No Content

and a matching X-Hook-Secret header to confirm that this
webhook subscription is indeed expected. We strongly recommend storing
this secret to be used to verify future webhook event signatures.

The POST request to create the webhook will then return with the status
of the request. If you do not acknowledge the webhook’s confirmation
handshake it will fail to setup, and you will receive an error in
response to your attempt to create it. This means you need to be able to
receive and complete the webhook while the POST request is in-flight
(in other words, have a server that can handle requests asynchronously).

Invalid hostnames like localhost will recieve a 403 Forbidden status code.

# Request
curl -H "Authorization: Bearer <personal_access_token>" \
-X POST https://app.asana.com/api/1.0/webhooks \
-d "resource=8675309" \
-d "target=https://example.com/receive-webhook/7654"

# Handshake sent to https://example.com/
POST /receive-webhook/7654
X-Hook-Secret: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81

# Handshake response sent by example.com
HTTP/1.1 200
X-Hook-Secret: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81

# Response
HTTP/1.1 201
{
  "data": {
    "gid": "43214",
    "resource": {
      "gid": "8675309",
      "name": "Bugs"
    },
    "target": "https://example.com/receive-webhook/7654",
    "active": false,
    "last_success_at": null,
    "last_failure_at": null,
    "last_failure_content": null
  }
}

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://app.asana.com/api/1.0/webhooks' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "filters": [
            {
                "action": "changed",
                "fields": [
                    "due_at",
                    "due_on",
                    "dependencies"
                ],
                "resource_subtype": "milestone",
                "resource_type": "task"
            }
        ],
        "resource": "12345",
        "target": "https://example.com/receive-webhook/7654?app_specific_param=app_specific_value"
    }
}'

Response Example

201 - Example 1

{
    "data": {
        "gid": "12345",
        "resource_type": "task",
        "active": false,
        "resource": {
            "gid": "12345",
            "resource_type": "task",
            "name": "Bug Task"
        },
        "target": "https://example.com/receive-webhook/7654",
        "created_at": "2012-02-22T02:06:58.147Z",
        "filters": [
            {
                "action": "changed",
                "fields": [
                    "due_at",
                    "due_on",
                    "dependencies"
                ],
                "resource_subtype": "milestone",
                "resource_type": "task"
            }
        ],
        "last_failure_at": "2012-02-22T02:06:58.147Z",
        "last_failure_content": "500 Server Error\\n\\nCould not complete the request",
        "last_success_at": "2012-02-22T02:06:58.147Z"
    }
}

Request

Body Params application/json

data

object (WebhookRequest)

optional

filters

array[object (WebhookFilter) {4}]

optional

An array of WebhookFilter objects to specify a whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.

resource

string

required

A resource ID to subscribe to. Many Asana resources are valid to create webhooks on, but higher-level resources require filters.

Example:

12345

target

string <uri>

required

The URL to receive the HTTP POST. The full URL will be used to deliver events from this webhook (including parameters) which allows encoding of application-specific state when the webhook is created.

Example:

https://example.com/receive-webhook/7654?app_specific_param=app_specific_value

Examples

Responses

🟢201Successfully created the requested webhook.

application/json

Body

data

object (WebhookResponse)

optional

Webhook objects represent the state of an active subscription for a server to be updated with information from Asana. This schema represents the subscription itself, not the objects that are sent to the server. For information on those please refer to the Event schema.

created_at

string <date-time>

read-onlyoptional

The time at which this resource was created.

Example:

2012-02-22T02:06:58.147Z

filters

array[object (WebhookFilter) {4}]

optional

Whitelist of filters to apply to events from this webhook. If a webhook event passes any of the filters the event will be delivered; otherwise no event will be sent to the receiving server.

last_failure_at

string <date-time>

read-onlyoptional

The timestamp when the webhook last received an error when sending an event to the target.

Example:

2012-02-22T02:06:58.147Z

last_failure_content

string

read-onlyoptional

The contents of the last error response sent to the webhook when attempting to deliver events to the target.

Example:

500 Server Error\n\nCould not complete the request

last_success_at

string <date-time>

read-onlyoptional

The timestamp when the webhook last successfully sent an event to the target.

Example:

2012-02-22T02:06:58.147Z

gid

string

read-onlyoptional

Globally unique identifier of the resource, as a string.

Example:

12345

resource_type

string

read-onlyoptional

The base type of this resource.

Example:

task

active

boolean

read-onlyoptional

If true, the webhook will send events - if false it is considered inactive and will not generate events.

Example:

false

resource

object

AsanaNamedResource

optional

A generic Asana Resource, containing a globally unique identifier.

target

string <uri>

read-onlyoptional

The URL to receive the HTTP POST.

Example:

https://example.com/receive-webhook/7654

🟠400400

🟠401401

🟠403403

🟠404404

🔴500500

Get multiple webhooks

Delete a webhook