asana-webhooks

Asana Webhooks

When to Use This Skill

• How do I receive Asana webhooks?
• How do I implement the Asana X-Hook-Secret handshake?
• How do I verify Asana webhook signatures (X-Hook-Signature)?
• How do I handle task, project, or story events (added, changed, removed, deleted, undeleted)?
• Why is my Asana webhook signature verification failing?

How Asana Webhooks Work

Asana webhooks have two phases that both POST to your target URL:

1. Handshake (once, at creation). When you call POST /webhooks, Asana sends a request carrying an X-Hook-Secret header and no X-Hook-Signature. Your endpoint must echo that same X-Hook-Secret back as a response header and return 200. Store the secret — it is the key for verifying every future delivery. This secret is shown only during the handshake.
2. Event deliveries (ongoing). Every later request carries an X-Hook-Signature header — a hex HMAC-SHA256 of the raw request body, keyed with the stored secret. The body is a batch: {"events": [...]}. Heartbeats arrive as {"events": []}.

Verification (core)

Distinguish the handshake from a normal delivery by which header is present, then HMAC the raw body and compare timing-safe.

Node:

const crypto = require('crypto');

function verifyAsanaSignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signatureHeader, 'hex'),
      Buffer.from(expected, 'hex')
    );
  } catch {
    return false; // wrong length / malformed hex
  }
}

// Handshake: echo X-Hook-Secret, store it, return 200.
// Delivery: verifyAsanaSignature(rawBody, req.headers['x-hook-signature'], storedSecret)

Python:

import hmac, hashlib

def verify_asana_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not secret:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)