Asana
  1. Webhooks
Asana
  • Attachments
    • Delete an attachment
      DELETE
    • Get an attachment
      GET
    • Get attachments for a task
      GET
    • Upload an attachment
      POST
  • Batch API
    • Submit parallel requests
      POST
  • Custom Fields
    • Create a custom field
      POST
    • Delete a custom field
      DELETE
    • Get a custom field
      GET
    • Update a custom field
      PUT
    • Create an enum option
      POST
    • Reorder a custom field's enum
      POST
    • Update an enum option
      PUT
    • Get a workspace's custom fields
      GET
  • Events
    • Get events on a resource
      GET
  • Goals
    • Get goals
      GET
    • Create a goal
      POST
    • Delete a goal
      DELETE
    • Get a goal
      GET
    • Update a goal
      PUT
    • Add a collaborator to a goal
      POST
    • Add a subgoal to a parent goal
      POST
    • Add a project/portfolio as supporting work for a goal.
      POST
    • Get parent goals from a goal
      GET
    • Remove a collaborator from a goal
      POST
    • Remove a subgoal from a goal
      POST
    • Remove a project/portfolio as supporting work for a goal.
      POST
    • Create a goal metric
      POST
    • Update a goal metric
      POST
    • Get subgoals from a goal
      GET
    • Get supporting work from a goal
      GET
  • Jobs
    • Get a job by id
  • Organization Exports
    • Create an organization export request
    • Get details on an org export request
  • Teams
    • Get teams in an organization
    • Create a team
    • Get a team
    • Add a user to a team
    • Remove a user from a team
    • Get teams for a user
  • Portfolio Memberships
    • Get multiple portfolio memberships
    • Get a portfolio membership
    • Get memberships from a portfolio
  • Portfolios
    • Get multiple portfolios
    • Create a portfolio
    • Delete a portfolio
    • Get a portfolio
    • Update a portfolio
    • Add a custom field to a portfolio
    • Add a portfolio item
    • Add users to a portfolio
    • Get portfolio items
    • Remove a custom field from a portfolio
    • Remove a portfolio item
    • Remove users from a portfolio
  • Custom Field Settings
    • Get a portfolio's custom fields
    • Get a project's custom fields
  • Project Memberships
    • Get a project membership
    • Get memberships from a project
  • Project Statuses
    • Delete a project status
    • Get a project status
    • Get statuses from a project
    • Create a project status
  • Projects
    • Get multiple projects
    • Create a project
    • Delete a project
    • Get a project
    • Update a project
    • Add a custom field to a project
    • Add followers to a project
    • Add users to a project
    • Duplicate a project
    • Remove a custom field from a project
    • Remove followers from a project
    • Remove users from a project
    • Get task count of a project
    • Get projects a task is in
    • Get a team's projects
    • Create a project in a team
    • Get all projects in a workspace
    • Create a project in a workspace
  • Sections
    • Get sections in a project
    • Create a section in a project
    • Move or Insert sections
    • Delete a section
    • Get a section
    • Update a section
    • Add task to section
  • Tasks
    • Get tasks from a project
    • Get tasks from a section
    • Get tasks from a tag
    • Get multiple tasks
    • Create a task
    • Delete a task
    • Get a task
    • Update a task
    • Set dependencies for a task
    • Set dependents for a task
    • Add followers to a task
    • Add a project to a task
    • Add a tag to a task
    • Get dependencies from a task
    • Get dependents from a task
    • Duplicate a task
    • Unlink dependencies from a task
    • Unlink dependents from a task
    • Remove followers from a task
    • Remove a project from a task
    • Remove a tag from a task
    • Set the parent of a task
    • Get subtasks from a task
    • Create a subtask
    • Get tasks from a user task list
    • Search tasks in a workspace
  • Stories
    • Delete a story
    • Get a story
    • Update a story
    • Get stories from a task
    • Create a story on a task
  • Tags
    • Get multiple tags
    • Create a tag
    • Delete a tag
    • Get a tag
    • Update a tag
    • Get a task's tags
    • Get tags in a workspace
    • Create a tag in a workspace
  • Team Memberships
    • Get team memberships
    • Get a team membership
    • Get memberships from a team
    • Get memberships from a user
  • Users
    • Get users in a team
    • Get multiple users
    • Get a user
    • Get a user's favorites
    • Get users in a workspace or organization
  • Time Periods
    • Get time periods
    • Get a time period
  • User Task Lists
    • Get a user task list
    • Get a user's task list
  • Workspace Memberships
    • Get workspace memberships for a user
    • Get a workspace membership
    • Get the workspace memberships for a workspace
  • Webhooks
    • Get multiple webhooks
      GET
    • Establish a webhook
      POST
    • Delete a webhook
      DELETE
    • Get a webhook
      GET
  • Workspaces
    • Get multiple workspaces
    • Get a workspace
    • Update a workspace
    • Add a user to a workspace or organization
    • Remove a user from a workspace or organization
  • Typeahead
    • Get objects via typeahead
  1. Webhooks

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 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 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
Modified at 2022-09-13 02:00:32
Previous
Get multiple webhooks
Next
Delete a webhook
Built with