Skip to content
HookDeploy

Asana webhooks

Last verified against Asana's documentation on September 27, 2026.

On this page ↓

Asana sends webhooks when tasks, projects, stories, and other resources change. Creating one involves a handshake that happens while your create request is still waiting: Asana sends an X-Hook-Secret header, and your URL has to echo it back. After that, events arrive in compact batches signed with that secret, and a webhook that can’t deliver for 24 hours is deleted. This page covers what Asana sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Asana sends webhooks for

Webhooks watch a resource, such as a task, project, or portfolio, and report added, changed, removed, deleted, and undeleted actions on it and the resources inside it. Filters narrow which resource types, actions, and fields you hear about, and are required for workspace, team, portfolio, and goal webhooks.

Each delivery is a JSON POST with an events array. Events are compact: they name the action, the resource and its type, the parent, and a created_at timestamp. Fetch the resource from Asana’s API for its current state.

How Asana delivers webhooks

BehaviorDetail
HandshakeOn creation, a POST with an X-Hook-Secret header. The URL must respond with 200 or 204 and the same X-Hook-Secret header
SecretThe X-Hook-Secret value, also returned in the create webhook API response
Signature headerX-Hook-Signature: hex HMAC-SHA256 of the raw body, keyed with the secret
BatchesEach delivery holds an events array
HeartbeatsEmpty {"events": []} deliveries, roughly every 8 hours
FailuresFailed deliveries are retried. A webhook with no successful delivery for 24 hours is deleted
MonitoringGET /webhooks/{gid} reports last_success_at, last_failure_at, and failure_deletion_timestamp

Common Asana webhook errors and how to fix them

Webhook creation hangs or fails

Asana holds your create request open until the handshake completes. If your URL can’t answer while that request is in flight, creation fails. The response needs the same X-Hook-Secret header, not just a 200.

Signature never matches

  • Wrong secret. Each webhook has its own secret. Store it per webhook, keyed by the webhook’s gid.
  • Parsed body. Hash the raw bytes.
  • Encoding. The header is lowercase hex.

Webhook deleted

A webhook with no successful delivery for 24 hours is deleted. Check failure_deletion_timestamp on the webhook to see when that will happen, and fix the endpoint before then.

Empty deliveries

{"events": []} is a heartbeat. Acknowledge it with a 200, and verify its signature like any other delivery.

Acting on stale data

Events are compact and can arrive late. Fetch the resource from the API before acting.

Why use HookDeploy with Asana

Never get deleted

HookDeploy captures every Asana webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Asana sees successful deliveries even while your server is down, so the webhook is never deleted for failing.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

Complete the handshake without code

Turn on the Asana handshake preset on the endpoint’s Security tab, under Verification (Starter and above). HookDeploy echoes the X-Hook-Secret header while your create request is waiting. It doesn’t store the handshake, so the secret never appears in your request history. Your app takes it from the create webhook response instead.

One webhook, many systems

Send each Asana event to your app, a reporting database, and a team channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Asana can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so an internal tool or database in a private network can receive Asana events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Asana events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Transformations. A transformation changes the body, and then X-Hook-Signature won’t verify at that destination.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Asana treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Signatures, retries, and replays

Asana’s signature covers only the body, with no timestamp, and HookDeploy forwards the body and X-Hook-Signature header unchanged, so retries and replays verify like the original delivery. A privacy filter that changes the stored copy used for retries and replays breaks the signature.

The handshake preset runs after HookDeploy’s token check, so if your endpoint requires a token, register the target URL with ?token= added. HookDeploy removes the token before forwarding.

The same events can arrive more than once. Deduplicate on each event’s resource, action, and created_at.

Set up Asana with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Asana events) and copy its URL.
  2. On the endpoint’s Security tab, under Verification, choose Asana and save (Starter and above).
  3. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  4. Create the webhook with Asana’s API, POST /webhooks, using your HookDeploy URL as the target. Store the X-Hook-Secret from the response with the webhook’s gid.
  5. Change the watched resource in Asana, and confirm the events appear in HookDeploy and reach your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/asana', express.raw({ type: 'application/json' }), async (req, res) => {
  const secret = await getStoredSecret();   // the X-Hook-Secret from the create webhook response
  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  const received = req.get('x-hook-signature') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid signature');

  res.sendStatus(200);
  const { events } = JSON.parse(req.body.toString('utf8'));
  for (const event of events) {            // empty for heartbeats
    await enqueue({ action: event.action, resource: event.resource, createdAt: event.created_at });
  }
  // Deduplicate, then fetch each resource from Asana's API before acting.
});

FAQ

How does the Asana webhook handshake work?

When you create a webhook, Asana posts to your URL with an X-Hook-Secret header while your create request waits. Your URL must respond with a 200 or 204 and the same X-Hook-Secret header. With HookDeploy, the Asana handshake preset does this for you.

Where do I get the Asana webhook secret if HookDeploy answers the handshake?

From Asana's create webhook API response, which includes the X-Hook-Secret. Store it with the webhook, and use it to verify X-Hook-Signature on every event.

How do I verify an Asana webhook?

Compute a hex HMAC-SHA256 of the raw request body using the webhook's secret, and compare it to the X-Hook-Signature header with a constant-time comparison.

Why was my Asana webhook deleted?

Asana deletes a webhook that has no successful delivery for 24 hours. The failure_deletion_timestamp on the webhook shows when that will happen.

What is an Asana webhook with an empty events array?

A heartbeat. Asana sends them roughly every 8 hours. Acknowledge them with a 200 and verify their signature like any other delivery.

Does HookDeploy break Asana signature verification?

No. The signature covers only the body, and HookDeploy forwards the body and X-Hook-Signature header unchanged, so first deliveries, retries, and replays all verify.

Capture Asana webhooks free

Start free