Skip to content
HookDeploy

Trello webhooks

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

On this page ↓

Trello sends webhooks when something happens to a board, list, card, or member you’re watching. Creating one requires your URL to answer a HEAD request with 200. Each delivery is signed with an HMAC-SHA1 over the body and the callback URL, and Trello’s own example builds that from a re-serialized body, which is where most verification bugs start. Trello retries only 3 times. This page covers what Trello sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Trello sends webhooks for

A webhook watches one model (a board, list, card, or member) by its ID and reports every action on it: createCard, updateCard, commentCard, addMemberToCard, moveCardToBoard, and many more.

Each delivery is a JSON POST with an action object (with its id, type, date, and data), the watched model, and the webhook itself, including its consecutiveFailures count.

How Trello delivers webhooks

BehaviorDetail
Creation checkA HEAD request to the callback URL, which must return 200
Method and formatPOST with a JSON body
Signature headerX-Trello-Webhook: base64 HMAC-SHA1 of the raw body followed by the callback URL, keyed with your app’s secret
Timeout30 seconds
Retries3
DeletionA 410 Gone response deletes the webhook, and so does revoking the token it’s bound to
Deduplicationaction.id

Common Trello webhook errors and how to fix them

Webhook creation fails

Trello’s HEAD request didn’t get a 200, or the certificate is invalid. Many frameworks don’t route HEAD to a POST handler.

Signature never matches

  • Re-serialized body. Trello’s own example hashes JSON.stringify(request.body). Hash the raw body instead.
  • Wrong URL. The signed content ends with the callback URL exactly as registered, byte for byte. Behind a proxy, your app sees a different URL.
  • Wrong algorithm or key. It’s SHA-1, keyed with your app’s secret, base64-encoded.

Webhook disappeared

A 410 response deletes it, and so does revoking or expiring its token. Don’t return 410 for anything but an intentional unsubscribe.

Events lost during short outages

Trello retries only 3 times. Check webhook.consecutiveFailures in deliveries to spot trouble early.

Why use HookDeploy with Trello

Capture every event

HookDeploy captures every Trello webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Trello’s 3 retries stop mattering, because the event is already safe in HookDeploy.

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

Answer the HEAD check without noise

Turn on the Trello handshake preset on the endpoint’s Security tab, under Verification (Starter and above). HookDeploy answers Trello’s HEAD check with 200 and doesn’t capture it, so these checks never fill your request history or reach your destinations.

One webhook, many systems

Send each Trello 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 Trello 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 Trello events with no public endpoint.

Develop against real events

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

Know the limits

  • Signatures and URLs. Trello signs the HookDeploy URL you registered, so your handler must use that URL when it verifies. See below.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Trello treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Signatures through HookDeploy

Trello signs the callback URL you registered, which with HookDeploy is your HookDeploy endpoint URL. HookDeploy forwards the body and X-Trello-Webhook header unchanged, so your handler can verify the signature, as long as it uses that registered HookDeploy URL, not its own.

If you add an endpoint token to the URL as ?token=, it’s part of the registered URL, so include it when you verify. HookDeploy removes the token before forwarding, so read the full registered URL from configuration rather than rebuilding it from the request.

The signature has no timestamp, so retries and replays verify like the original delivery. Deduplicate on action.id.

Set up Trello with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Trello boards) and copy its URL.
  2. On the endpoint’s Security tab, under Verification, choose Trello 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 Trello’s API, POST /1/webhooks, using your HookDeploy URL as the callbackURL and the board or card ID as idModel.
  5. Change the watched board, and confirm the event appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

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

const app = express();
// The callback URL exactly as registered with Trello: your HookDeploy URL, query string included.
const CALLBACK_URL = process.env.TRELLO_CALLBACK_URL;

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/trello', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = crypto
    .createHmac('sha1', process.env.TRELLO_APP_SECRET)
    .update(Buffer.concat([req.body, Buffer.from(CALLBACK_URL)]))   // raw body, then the URL
    .digest('base64');
  const received = req.get('x-trello-webhook') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid signature');   // never 410: that deletes the webhook

  res.sendStatus(200);
  const { action } = JSON.parse(req.body.toString('utf8'));
  await enqueue({ actionId: action.id, type: action.type, data: action.data });
  // Deduplicate on actionId in your worker.
});

FAQ

Why does Trello webhook creation fail?

Trello sends a HEAD request to your callback URL when you create a webhook, and only creates it if that returns a 200. With HookDeploy, the Trello handshake preset answers it.

How is the X-Trello-Webhook signature calculated?

It's a base64-encoded HMAC-SHA1 of the raw request body followed by the callback URL exactly as registered, keyed with your Trello app's secret.

Why does my Trello signature check fail?

Usually because the body was re-serialized, as in Trello's own example, or because the URL doesn't match the registered callback URL byte for byte. Hash the raw body, and read the callback URL from configuration.

How many times does Trello retry a webhook?

3 times, with a 30-second timeout per attempt.

Why was my Trello webhook deleted?

A 410 Gone response deletes it, and so does revoking or expiring the token it was created with.

Does HookDeploy break Trello signature verification?

Not if you verify with the right URL. Trello signs the HookDeploy URL you registered, and HookDeploy forwards the body and signature unchanged. Your handler must use that registered URL, including any query string.

Capture Trello webhooks free

Start free