Sample - Asana API
POST/webhooks

Create a webhook subscription

Creates a webhook subscription for a resource and delivers events to the specified target URL. Supply resource and target in the data block, then complete the confirmation handshake while the creation request remains in flight. The target must return the X-Hook-Secret value in a successful handshake response before the webhook is established.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 1 body field
opt_fieldsarray<string>optional
Comma-separated optional webhook properties to include in the response, such as `active`, `filters`, `last_success_at`, and `next_attempt_after`.

Webhook subscription details, including the resource to monitor and the URL that receives event notifications.

dataobjectoptional
The webhook configuration containing `resource`, `target`, and optional event `filters`.

6 status codes
201Returns the created webhook, including its resource, target, active status, delivery timestamps, and an `X-Hook-Secret` for verifying future event signatures.
dataobjectoptional
X-Hook-Secretstringoptional
The secret to be used to verify future webhook event signatures.
400Returned when the required webhook data is missing or malformed, or when the target does not complete the confirmation handshake.
errorsarray<object>optional
401Returned when a valid authentication token is not provided.
errorsarray<object>optional
403Returned when the authenticated user lacks access, the required `webhooks:write` scope, or the target hostname is invalid.
errorsarray<object>optional
404Returned when the request path does not specify a known action or the subscribed resource does not exist.
errorsarray<object>optional
500Returned when a server-side problem prevents webhook creation; the response may include an error phrase.
errorsarray<object>optional

Error handling

A 400 is returned when resource, target, or the request syntax is invalid, or when the confirmation handshake is not completed successfully. A 401 is returned without a valid authentication token, and a 403 is returned for an inaccessible resource or invalid hostname such as localhost; the authenticated user also needs the webhooks:write scope. A 404 indicates an unknown action or resource, while a 500 indicates a server-side failure.