Register and verify a Trello board webhook for card changes

Problem and useful takeaway

Polling Trello's REST API to detect card moves, list changes, or membership updates consumes rate limits and delays notification until the next poll runs. Trello webhooks push JSON action notifications to a callback URL you control, but the payload identifies the action and affected model rather than shipping the full board state. A receiver that does slow work inside the webhook handler risks timeouts, delivery backoff, and eventual webhook disablement.

Takeaway: register one webhook per board, make the endpoint answer with HTTP 200 immediately, enqueue the notification for background processing, fetch any additional context from the Trello REST API, and process each action idempotently. Verify the flow on a test board before enabling it in production.

Prerequisites

• A Trello board you own or can modify, with its board ID.
• A Trello API key and API token. The token must have access to the board you intend to watch.
• A publicly reachable HTTPS callback URL for your receiver. Trello must be able to connect to it during registration validation.
• A receiver service that can parse JSON, return HTTP 200 quickly, and enqueue work for later processing.

Terms: a webhook is an HTTP callback Trello calls when a watched model changes. idModel is Trello's identifier for the board, card, list, or other model being monitored. Idempotent processing means handling the same notification more than once without causing duplicate or incorrect side effects.

Register the webhook

Send a POST request to Trello's webhooks endpoint. Run this from a terminal or build host that can reach api.trello.com. You need the API key and token with board access.

curl -X POST "https://api.trello.com/1/webhooks?key=YOUR_API_KEY&token=YOUR_API_TOKEN" -H "Content-Type: application/json" -d "{\"description\":\"Board change receiver\",\"callbackURL\":\"https://your-receiver.example.com/trello/webhook\",\"idModel\":\"YOUR_BOARD_ID\"}"

Placeholders: replace YOUR_API_KEY, YOUR_API_TOKEN, YOUR_BOARD_ID, and the callback URL with your own values. Expected check: Trello returns HTTP 200 and a JSON object containing the webhook id and description. Trello validates the callback URL before activation; an unreachable URL or one that does not answer promptly fails registration. Risk: repeated receiver errors or timeouts can cause Trello to back off or disable the webhook.

Confirm registration

curl -G "https://api.trello.com/1/tokens/YOUR_API_TOKEN/webhooks?key=YOUR_API_KEY"

Expected check: the response array includes the webhook you just registered, with the board ID as its idModel. If it is missing, registration did not complete or the webhook was already disabled.

Build the receiver

The receiver endpoint should do as little as possible inside the HTTP request:

1. Acknowledge immediately with HTTP 200. Do not call external APIs, write to slow storage, or run business logic before responding.
2. Parse the JSON body and extract the Trello action ID and action type.
3. Enqueue the notification in a durable queue for background workers.
4. In the worker, check whether the action ID has already been processed. If yes, skip it. If no, use the action's model IDs (for example, idCard or idBoard) to call the Trello REST API and fetch the context your integration needs.

Trello webhook payloads do not include full board state. A card-move notification tells you which card changed and what changed, but your service must request card or board details separately if it needs names, members, or custom field values.

Test on a sample board

1. Create or use a board that contains no production data.
2. Register the webhook against that board.
3. Move a card to a different list or rename a list.
4. Inspect your receiver logs for an incoming POST with action.type matching the change, such as updateCard or updateList.
5. Confirm your worker can fetch the affected card or board through the Trello REST API using the IDs in the payload.

Do not assume delivery order or exactly-once delivery. Treat the webhook as a signal, not a complete record, and keep a fallback poll of recent board actions if missing events would break your process.

Remove a test webhook

Deleting a webhook changes state, so remove it after testing to avoid leaving orphaned subscriptions.

curl -X DELETE "https://api.trello.com/1/webhooks/YOUR_WEBHOOK_ID?key=YOUR_API_KEY&token=YOUR_API_TOKEN"

Expected check: HTTP 200 or 204, and a subsequent token webhook list no longer contains YOUR_WEBHOOK_ID. If the receiver continues failing after you fix it, delete the production webhook, correct the receiver, and register a new one. Trello may delete a webhook implicitly when the board is deleted or the authorizing token is revoked; monitor token status separately and re-register after re-authorization.

Limitations and verification status

• One webhook watches a single model. Multiple boards require separate webhooks; organization-level options depend on current Trello support and should be confirmed before use.
• Trello may change callback validation or retry behavior. Confirm current handshake requirements before relying on automation in production.
• This draft summarizes established webhook behavior from the research brief. Verify registration validation, retry timing, and payload fields against Trello's current developer documentation before deploying to production.

Practical result check: after registration, move a card on the test board, confirm the receiver logs a matching action, then delete the test webhook and confirm it disappears from your token's webhook list.