Trello Webhooks Skill

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).

For complete handlers with route wiring, event dispatch, HEAD handling, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/

Common Event Types

Trello's event type is in the payload at action.type (there is no event header). The watched object is in model, and the webhook config is in webhook.

For the full list of action types, see Trello action types.

Environment Variables

TRELLO_SECRET=your_oauth1_application_secret       # Power-Up management page → API Key tab
TRELLO_CALLBACK_URL=https://example.com/webhooks/trello  # Must match the URL registered at webhook creation, exactly

Creating a Webhook

Trello webhooks are created via the API only (there is no dashboard toggle):

curl -X POST "https://api.trello.com/1/tokens/{token}/webhooks/" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "callbackURL": "https://example.com/webhooks/trello",
    "idModel": "ID_OF_BOARD_CARD_OR_LIST",
    "description": "My webhook"
  }'

See references/setup.md for the full flow.

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 trello --path /webhooks/trello

Reference Materials

• references/overview.md - Trello webhook concepts and payload structure
• references/setup.md - Creating webhooks via the API
• references/verification.md - Signature verification details and gotchas