Answer
For boards that churn cards at a high rate, a hybrid strategy—process the webhook payload first and issue a GET /cards/{id} only when the payload is missing a required field—offers the best trade‑off between reliability and API costs. It guarantees the latest state for critical operations while keeping the average number of API calls close to the webhook‑only baseline.
Why this works
- Webhook events arrive in near‑real‑time, so the initial payload usually contains the most recent data.
- Only a small subset of actions (e.g., card moved to a different list or updated with a new description) need a fresh snapshot; the rest can be handled with the webhook data.
- Conditional GETs keep the request volume proportional to the number of “edge” cases, rather than a blanket fetch for every event.
Confirmed facts from Trello’s design
- Webhook payloads contain
id, name, idBoard, and minimal state; they are not guaranteed to be the final version of the card. - GET /cards/{id} with the
fields query parameter can limit the response to the fields you actually need, reducing payload size and rate‑limit impact. - High‑turnover boards increase the chance that a card is moved or updated between webhook dispatch and a follow‑up GET, which can cause 404/410 responses; a conditional GET only runs when the webhook lacks those fields, lowering the chance of a stale 404.
Practical steps for a production‑scale integration
- Receive the webhook and parse the JSON. Store the event in a queue for idempotent processing.
- Check required fields (e.g.,
desc, labels, due) in the payload. If all are present, proceed without additional API calls. - When a field is missing or marked
unknown, issue a GET request with ?fields=desc,labels,due (adjust the list to your needs). Handle 404/410 by treating the card as deleted or by retrying after a short back‑off. - Use the
X-RateLimit-Remaining header to monitor consumption. If the remaining quota drops below a threshold (e.g., 100 requests), throttle the conditional GETs or batch them. - Log each GET response and compare it to the webhook data to verify consistency. Store the last known good state in a local cache or database.
Impact on rate limits
Because the GET is conditional, the average number of calls per event stays close to 1 (the webhook) plus p where p is the probability that the payload lacks a required field. On a board with 5 000 card events per minute and p ≈ 0.1, you’d issue roughly 500 extra GETs per minute—well below Trello’s 10 000‑request‑per‑10‑minute quota for most apps.
Hybrid strategy viability
In practice, the hybrid model keeps latency low (the conditional GET is only one HTTP round‑trip) and eliminates the risk of missing updates that a webhook‑only design would suffer from during downtime. It also avoids the 404/410 pitfalls of a blanket GET approach by only querying when the data is incomplete.
Missing diagnostic detail
To fine‑tune the threshold for conditional GETs and ensure you stay comfortably within rate limits, could you share the average number of card‑creation/update events per minute on the board? That will help set the p value and the back‑off window.
trello