{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"<b>Required scope: </b><code>webhooks:write</code>\n\nEstablishing a webhook is a two-part process. First, a simple HTTP POST\nrequest initiates the creation similar to creating any other resource.\n\nNext, in the middle of this request comes the confirmation handshake.\nWhen a webhook is created, we will send a test POST to the target with an\n`X-Hook-Secret` header. The target must respond with a `200 OK` or `204\nNo Content` and a matching `X-Hook-Secret` header to confirm that this\nwebhook subscription is indeed expected. We strongly recommend storing\nthis secret to be used to verify future webhook event signatures.\n\nThe POST request to create the webhook will then return with the status\nof the request. If you do not acknowledge the webhook’s confirmation\nhandshake it will fail to setup, and you will receive an error in\nresponse to your attempt to create it. This means you need to be able to\nreceive and complete the webhook *while* the POST request is in-flight\n(in other words, have a server that can handle requests asynchronously).\n\nInvalid hostnames like localhost will receive a 403 Forbidden status code.\n\n```\n# Request\ncurl -H \"Authorization: Bearer <personal_access_token>\" \\\n-X POST https://app.asana.com/api/1.0/webhooks \\\n-d \"resource=8675309\" \\\n-d \"target=https://example.com/receive-webhook/7654\"\n```\n\n```\n# Handshake sent to https://example.com/\nPOST /receive-webhook/7654\nX-Hook-Secret: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81\n```\n\n```\n# Handshake response sent by example.com\nHTTP/1.1 200\nX-Hook-Secret: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81\n```\n\n```\n# Response\nHTTP/1.1 201\n{\n  \"data\": {\n    \"gid\": \"43214\",\n    \"resource\": {\n      \"gid\": \"8675309\",\n      \"name\": \"Bugs\"\n    },\n    \"target\": \"https://example.com/receive-webhook/7654\",\n    \"active\": false,\n    \"last_success_at\": null,\n    \"last_failure_at\": null,\n    \"last_failure_content\": null\n  },\n  \"X-Hook-Secret\": \"b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81\"\n}\n```","properties":{"query":{"type":"object","properties":{"opt_pretty":{"type":"boolean","examples":[true],"description":"Provides “pretty” output.\nProvides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging."},"opt_fields":{"type":"array","items":{"type":"string","enum":["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"]},"examples":[["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"]],"description":"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](/docs/inputoutput-options#selecting-nested-fields)."}},"required":[],"additionalProperties":false},"body":{"type":"object","properties":{"data":{"$ref":"#/definitions/WebhookRequest"}}}},"required":["body"],"additionalProperties":false,"definitions":{"WebhookRequest":{"type":"object","properties":{"resource":{"description":"A resource ID to subscribe to. Many Asana resources are valid to create webhooks on, but higher-level resources require filters.","type":"string","examples":["12345"]},"target":{"description":"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.","type":"string","format":"uri","examples":["https://example.com/receive-webhook/7654?app_specific_param=app_specific_value"]},"filters":{"type":"array","description":"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.","items":{"allOf":[{"$ref":"#/definitions/WebhookFilter"},{"description":"A set of filters to specify a whitelist for what types of events will be delivered."},{"type":"object"}]}}},"required":["resource","target"]},"WebhookFilter":{"type":"object","description":"A WebhookFilter can be passed on creation of a webhook in order to filter the types of actions that trigger delivery of an [event](/reference/events)","properties":{"resource_type":{"type":"string","description":"The 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`.","examples":["task"]},"resource_subtype":{"description":"The 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.","type":"string","examples":["milestone"]},"action":{"type":"string","description":"The type of change on the **resource** to pass through the filter. For more information refer to `Event.action` in the [event](/reference/events) schema. This can be one of `changed`, `added`, `removed`, `deleted`, and `undeleted` depending on the nature of what has occurred on the resource.","examples":["changed"]},"fields":{"type":"array","description":"*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`\n*Note: Subscriptions created on higher-level resources such as a Workspace, Team, or Portfolio do not support fields.*","items":{"type":"string"},"examples":[["due_at","due_on","dependencies"]]}}}}},"name":"Establish a webhook","id":"asana.createwebhook","example":{"body":{}},"maxRequests":1,"summary":false}}