Webhooks

Webhooks allow you to subscribe to notifications about events that occur on Asana resources (e.g., tasks, projects, stories, etc.).

📘

Webhooks tutorial

For a more detailed explanation of webhooks see the overview of webhooks.


WebhookCompact

A Compact object reflects the default fields returned after a successful API request. See input/output options to include more fields in the response.

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
activebooleanIf true, the webhook will send events - if false it is considered inactive and will not generate events.
resourceobjectA generic Asana Resource, containing a globally unique identifier.
resource.gidstringGlobally unique identifier of the resource, as a string.
resource.resource_typestringThe base type of this resource.
resource.namestringThe name of the object.
targetstring(uri)The URL to receive the HTTP POST.
{
  "gid": "12345",
  "resource_type": "webhook",
  "active": false,
  "resource": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Bug Task"
  },
  "target": "https://example.com/receive-webhook/7654"
}

Webhook

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.

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
activebooleanIf true, the webhook will send events - if false it is considered inactive and will not generate events.
resourceobjectA generic Asana Resource, containing a globally unique identifier.
resource.gidstringGlobally unique identifier of the resource, as a string.
resource.resource_typestringThe base type of this resource.
resource.namestringThe name of the object.
targetstring(uri)The URL to receive the HTTP POST.
created_atstring(date-time)The time at which this resource was created.
filters[object]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.
» {}.actionstringThe type of change on the resource to pass through the filter. For more information refer to Event.action in the event schema. This can be one of changed, added, removed, deleted, and undeleted depending on the nature of what has occurred on the resource.
» {}.fields[string]Conditional. A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for action of type changed
» {}.resource_subtypestringThe resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the resource_subtype field on the resources themselves.
» {}.resource_typestringThe type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to task.
last_failure_atstring(date-time)The timestamp when the webhook last received an error when sending an event to the target.
last_failure_contentstringThe contents of the last error response sent to the webhook when attempting to deliver events to the target.
last_success_atstring(date-time)The timestamp when the webhook last successfully sent an event to the target.
{
  "gid": "12345",
  "resource_type": "webhook",
  "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"
}

WebhookFilter

A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an event

PropertyTypeDescription
actionstringThe type of change on the resource to pass through the filter. For more information refer to Event.action in the event schema. This can be one of changed, added, removed, deleted, and undeleted depending on the nature of what has occurred on the resource.
fields[string]Conditional. A whitelist of fields for events which will pass the filter when the resource is changed. These can be any combination of the fields on the resources themselves. This field is only valid for action of type changed
resource_subtypestringThe resource subtype of the resource that the filter applies to. This should be set to the same value as is returned on the resource_subtype field on the resources themselves.
resource_typestringThe type of the resource which created the event when modified; for example, to filter to changes on regular tasks this field should be set to task.
{
  "action": "changed",
  "fields": [
    "due_at",
    "due_on",
    "dependencies"
  ],
  "resource_subtype": "milestone",
  "resource_type": "task"
}