Webhooks

Establish a webhook

<b>Required scope: </b><code>webhooks:write</code>

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 receive 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
  },
  "X-Hook-Secret": "b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81"
}
post/webhooks

Request

  • Base URL: https://app.asana.com/api/1.0
  • URL: https://app.asana.com/api/1.0/webhooks
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://app.asana.com/-/oauth_authorize, token URL https://app.asana.com/-/oauth_token, scopes: webhooks:write)

Query parameters

opt_fieldsstring[]

This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. Properties can include nested fields. To learn more, see the input/output options guide.

Request body

Example request

{
  "data": {
    "resource": "12345",
    "target": "https://example.com/receive-webhook/7654?app_specific_param=app_specific_value",
    "filters": [
      {
        "resource_type": "task",
        "resource_subtype": "milestone",
        "action": "changed",
        "fields": [
          "due_at",
          "due_on",
          "dependencies"
        ]
      }
    ]
  }
}

Response

Successfully created the requested webhook.

X-Hook-Secretstring

The secret to be used to verify future webhook event signatures.

Example response

{
  "data": {
    "gid": "12345",
    "resource_type": "webhook",
    "resource": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Bug Task"
    },
    "target": "https://example.com/receive-webhook/7654",
    "created_at": "2012-02-22T02:06:58.147Z",
    "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",
    "delivery_retry_count": 3,
    "next_attempt_after": "2012-02-22T02:06:58.147Z",
    "failure_deletion_timestamp": "2012-02-22T02:06:58.147Z",
    "filters": [
      {
        "resource_type": "task",
        "resource_subtype": "milestone",
        "action": "changed",
        "fields": [
          "due_at",
          "due_on",
          "dependencies"
        ]
      }
    ]
  },
  "X-Hook-Secret": "b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81"
}

Changes

No recorded changes to this operation across all 51 revisions of this API.