Skip to content

Latest commit

 

History

History
273 lines (194 loc) · 13.3 KB

WebhooksApi.md

File metadata and controls

273 lines (194 loc) · 13.3 KB

asana.WebhooksApi

All URIs are relative to https://app.asana.com/api/1.0

Method HTTP request Description
create_webhook POST /webhooks Establish a webhook
delete_webhook DELETE /webhooks/{webhook_gid} Delete a webhook
get_webhook GET /webhooks/{webhook_gid} Get a webhook
get_webhooks GET /webhooks Get multiple webhooks
update_webhook PUT /webhooks/{webhook_gid} Update a webhook

create_webhook

Establish a webhook

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\" }

(more information)

Example

import asana
from asana.rest import ApiException
from pprint import pprint

configuration = asana.Configuration()
configuration.access_token = '<YOUR_ACCESS_TOKEN>'
api_client = asana.ApiClient(configuration)

# create an instance of the API class
webhooks_api_instance = asana.WebhooksApi(api_client)
body = {"data": {"<PARAM_1>": "<VALUE_1>", "<PARAM_2>": "<VALUE_2>",}} # dict | The webhook workspace and target.
opts = {
    'opt_fields': "active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target", # list[str] | This endpoint returns a compact 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.
}

try:
    # Establish a webhook
    api_response = webhooks_api_instance.create_webhook(body, opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling WebhooksApi->create_webhook: %s\n" % e)

Parameters

Name Type Description Notes
body Dict The webhook workspace and target.
opt_fields Dict This endpoint returns a compact 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. [optional]

Return type

dict

HTTP request headers

  • Content-Type: application/json; charset=UTF-8
  • Accept: application/json; charset=UTF-8

[Back to top] [Back to API list] [Back to README]

delete_webhook

Delete a webhook

This method permanently removes a webhook. Note that it may be possible to receive a request that was already in flight after deleting the webhook, but no further requests will be issued.

(more information)

Example

import asana
from asana.rest import ApiException
from pprint import pprint

configuration = asana.Configuration()
configuration.access_token = '<YOUR_ACCESS_TOKEN>'
api_client = asana.ApiClient(configuration)

# create an instance of the API class
webhooks_api_instance = asana.WebhooksApi(api_client)
webhook_gid = "12345" # str | Globally unique identifier for the webhook.


try:
    # Delete a webhook
    api_response = webhooks_api_instance.delete_webhook(webhook_gid)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling WebhooksApi->delete_webhook: %s\n" % e)

Parameters

Name Type Description Notes
webhook_gid str Globally unique identifier for the webhook.

Return type

dict

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json; charset=UTF-8

[Back to top] [Back to API list] [Back to README]

get_webhook

Get a webhook

Returns the full record for the given webhook.

(more information)

Example

import asana
from asana.rest import ApiException
from pprint import pprint

configuration = asana.Configuration()
configuration.access_token = '<YOUR_ACCESS_TOKEN>'
api_client = asana.ApiClient(configuration)

# create an instance of the API class
webhooks_api_instance = asana.WebhooksApi(api_client)
webhook_gid = "12345" # str | Globally unique identifier for the webhook.
opts = {
    'opt_fields': "active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target", # list[str] | This endpoint returns a compact 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.
}

try:
    # Get a webhook
    api_response = webhooks_api_instance.get_webhook(webhook_gid, opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling WebhooksApi->get_webhook: %s\n" % e)

Parameters

Name Type Description Notes
webhook_gid str Globally unique identifier for the webhook.
opt_fields Dict This endpoint returns a compact 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. [optional]

Return type

dict

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json; charset=UTF-8

[Back to top] [Back to API list] [Back to README]

get_webhooks

Get multiple webhooks

Get the compact representation of all webhooks your app has registered for the authenticated user in the given workspace.

(more information)

Example

import asana
from asana.rest import ApiException
from pprint import pprint

configuration = asana.Configuration()
configuration.access_token = '<YOUR_ACCESS_TOKEN>'
api_client = asana.ApiClient(configuration)

# create an instance of the API class
webhooks_api_instance = asana.WebhooksApi(api_client)
workspace = "1331" # str | The workspace to query for webhooks in.
opts = {
    'limit': 50, # int | Results per page. The number of objects to return per page. The value must be between 1 and 100.
    'offset': "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9", # str | Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. *Note: You can only pass in an offset that was returned to you via a previously paginated request.*
    'resource': "51648", # str | Only return webhooks for the given resource.
    'opt_fields': "active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,offset,path,resource,resource.name,target,uri", # list[str] | This endpoint returns a compact 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.
}

try:
    # Get multiple webhooks
    api_response = webhooks_api_instance.get_webhooks(workspace, opts)
    for data in api_response:
        pprint(data)
except ApiException as e:
    print("Exception when calling WebhooksApi->get_webhooks: %s\n" % e)

Parameters

Name Type Description Notes
workspace str The workspace to query for webhooks in.
limit int Results per page. The number of objects to return per page. The value must be between 1 and 100. [optional]
offset str Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. Note: You can only pass in an offset that was returned to you via a previously paginated request. [optional]
resource str Only return webhooks for the given resource. [optional]
opt_fields Dict This endpoint returns a compact 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. [optional]

Return type

generator

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json; charset=UTF-8

[Back to top] [Back to API list] [Back to README]

update_webhook

Update a webhook

An existing webhook's filters can be updated by making a PUT request on the URL for that webhook. Note that the webhook's previous filters array will be completely overwritten by the filters sent in the PUT request.

(more information)

Example

import asana
from asana.rest import ApiException
from pprint import pprint

configuration = asana.Configuration()
configuration.access_token = '<YOUR_ACCESS_TOKEN>'
api_client = asana.ApiClient(configuration)

# create an instance of the API class
webhooks_api_instance = asana.WebhooksApi(api_client)
body = {"data": {"<PARAM_1>": "<VALUE_1>", "<PARAM_2>": "<VALUE_2>",}} # dict | The updated filters for the webhook.
webhook_gid = "12345" # str | Globally unique identifier for the webhook.
opts = {
    'opt_fields': "active,created_at,delivery_retry_count,failure_deletion_timestamp,filters,filters.action,filters.fields,filters.resource_subtype,last_failure_at,last_failure_content,last_success_at,next_attempt_after,resource,resource.name,target", # list[str] | This endpoint returns a compact 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.
}

try:
    # Update a webhook
    api_response = webhooks_api_instance.update_webhook(body, webhook_gid, opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling WebhooksApi->update_webhook: %s\n" % e)

Parameters

Name Type Description Notes
body Dict The updated filters for the webhook.
webhook_gid str Globally unique identifier for the webhook.
opt_fields Dict This endpoint returns a compact 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. [optional]

Return type

dict

HTTP request headers

  • Content-Type: application/json; charset=UTF-8
  • Accept: application/json; charset=UTF-8

[Back to top] [Back to API list] [Back to README]