Retrying a 429 on a fixed timer
How you'll know: The job spends longer throttled than working.
Fix: Wait exactly the Retry-After seconds. The official client libraries retry for you up to a set maximum; a hand-rolled client needs the same.
Asana's REST API reaches tasks, subtasks, projects, sections, custom fields, comments and attachments, with webhooks for changes. Below is what you need while building. Rules are the one big exception, covered near the end. Still deciding what to connect, not how? The Asana hub covers that.
Base URL: https://app.asana.com/api/1.0. Responses come wrapped in a data object, and write requests send their body inside data too.
Auth: send Authorization: Bearer {token}. The token is a personal access token for your own scripts, or an OAuth access token when other people sign in to your app.
Fields: list endpoints return compact records (mostly gid and name). Ask for what you need with opt_fields, e.g. ?opt_fields=name,completed,assignee.email,custom_fields.
https://app.asana.com/-/oauth_token with grant_type=refresh_token. Request granular scopes such as tasks:read rather than full permissions where you can.Per authorization token. Every limiter answers with a 429 and a Retry-After header in seconds.
opt_fields on large lists are the usual cause.Add limit (1 to 100) to every list request. Some older endpoints don't paginate unless you do, and an unpaginated query is cut off at about 1,000 objects, or times out in a large organization.
The response carries next_page with an offset, a relative path and a full uri. Pass that offset on the next request. When next_page is null, you're done.
Watch for: offsets expire. Don't park a token overnight and expect to resume from it; restart the walk instead.
Webhooks save you polling, but they're not a guarantee. Plan the catch-up job on day one.
POST /webhooks with a resource (a project or task gid, for example) and your HTTPS target URL. Webhooks on a workspace, team, portfolio or goal must include filters, and they don't receive task, subtask or story events.
Before your create call returns, Asana sends a request to the target with an X-Hook-Secret header. Reply 200 or 204 with the same value in your own X-Hook-Secret header. Only then does the create call come back 201.
Watch for: the secret. Store it now, because it's not returned when you fetch the webhook later. And your receiver must already be live when you call create, or the handshake fails.
Each request carries X-Hook-Signature: an HMAC-SHA256 of the raw request body, keyed with that secret. Compute it over the raw bytes, not a re-serialized body, and reject anything that doesn't match.
The body has an events array, often several at once. Each event says what changed, not the new state, so fetch the resource with opt_fields to get current values. Use each event's created_at rather than arrival order.
Return 200 within 10 seconds and process from a queue. Asana retries failed deliveries with backoff for up to 24 hours, and sends a heartbeat every 8 hours. If nothing succeeds for 24 hours, the webhook is deleted.
Watch for: delivery is at-most-once and events can't be replayed. A scheduled job that compares Asana with your copy is the only way to be sure nothing was missed.
How you'll know: The job spends longer throttled than working.
Fix: Wait exactly the Retry-After seconds. The official client libraries retry for you up to a set maximum; a hand-rolled client needs the same.
How you'll know: No events for days, and the webhook no longer shows when you list them.
Fix: Your endpoint missed heartbeats for 24 hours, or the resource was deleted. Alert on last_success_at going stale, recreate the webhook, and run the catch-up job for the gap.
How you'll know: Someone renames a field and the sync writes blanks.
Fix: Store custom field gids, look them up once at start, and fail loudly when an expected field is gone.
How you'll know: Assignee, due date or custom field values come back empty.
Fix: Compact records are the default. Name every field you need in opt_fields, and keep the list short to stay inside the cost limit.
There's no endpoint to create a Rule or edit its triggers, conditions and actions. That stays in the Rule builder, as covered on our Asana automation page. What you can do, in beta, is fire one: give a Rule the Web request is received trigger in the builder, and Asana generates the endpoint POST /rule_triggers/{trigger_id}/run. Send it a target task and an action_data object, and the Rule runs with those values.
That makes a practical split. Let people who own the project keep the logic in a Rule they can read, and have outside systems call it. When the logic needs data Asana doesn't hold, or has to write to another system, it moves into code on the API instead.
Yes. There's no separate fee, and it works on the free tier. The plan changes what you get: free domains are limited to 150 requests a minute against 1,500 on paid ones, and service accounts need an Enterprise tier.
Yes. Subscribe to a project, task or other resource with POST /webhooks, complete the X-Hook-Secret handshake, and Asana sends batched events when it changes. Delivery is at-most-once, so pair it with a scheduled check.
1,500 requests a minute per token on paid domains and 150 on free ones, with separate caps of 60 a minute for search and 50 concurrent reads or 15 concurrent writes. Every limit returns a 429 with a Retry-After header.
No. Building or editing a Rule's logic happens in Asana's Rule builder. The API can only run a Rule that has the Web request is received trigger, which is in beta.
Yes. Asana publishes official client libraries, including ones for Node and Python, that handle authentication, pagination and 429 retries. Plain HTTP works just as well if you'd rather not take on a dependency.
Compute an HMAC-SHA256 of the raw request body using the secret from the handshake, and compare it with the X-Hook-Signature header. Reject the request if they differ.
That's regular work for n-frames: webhook receivers, two-way syncs with accounting and CRM systems, and bulk migrations into Asana, with the monitoring that tells you when a run fell short.