trello-webhooks

Trello Webhooks

When to Use This Skill

• How do I receive Trello webhooks?
• How do I verify Trello webhook signatures?
• How do I handle createCard, updateCard, or commentCard events?
• Why is my Trello x-trello-webhook signature verification failing?
• How do I create a Trello webhook and pass the HEAD validation check?

Verification (core)

Trello signs each delivery with HMAC-SHA1 keyed on your OAuth 1.0 application secret (the "OAuth1.0 secret" on your Power-Up's API Key tab). The signed content is the raw request body concatenated with the exact callback URL used when the webhook was created, and the digest is sent base64-encoded in the x-trello-webhook header. Use the raw body (never re-serialized JSON) and compare timing-safe.

Trello does not follow the Standard Webhooks spec, and the algorithm is SHA1, not SHA256. The callback URL is part of the signed content — a mismatch between the URL you registered and the TRELLO_CALLBACK_URL you verify against is the most common cause of verification failures.

Node:

const crypto = require('crypto');

function verifyTrelloWebhook(rawBody, signature, secret, callbackURL) {
  if (!signature) return false;
  const content = Buffer.concat([Buffer.from(rawBody), Buffer.from(callbackURL)]);
  const expected = crypto.createHmac('sha1', secret).update(content).digest('base64');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false; // length mismatch = invalid
  }
}

Python:

import hmac, hashlib, base64

def verify_trello_webhook(raw_body: bytes, signature: str, secret: str, callback_url: str) -> bool:
    if not signature:
        return False
    digest = hmac.new(secret.encode(), raw_body + callback_url.encode(), hashlib.sha1).digest()
    expected = base64.b64encode(digest).decode()
    return hmac.compare_digest(expected, signature)

HEAD check: When you create a webhook, Trello sends an HTTP HEAD request to the callback URL and creation fails unless it returns 200. Your endpoint must answer HEAD with 200 (an invalid SSL cert also fails creation; a missing cert does not).