Trello Webhooks and External Schema Synchronization

Answer to the Core Questions

1. Reliable detection of schema drift is achieved by periodically polling GET /1/boards/{boardId}/customFields (or the card‑level endpoint) and comparing the returned structure—field IDs, types, and option IDs—to a cached schema snapshot. Because field IDs and option IDs never change, any difference in the name, type, or options[*].value indicates a drift.

2. Maintaining data integrity for in‑flight payloads requires assigning each cached schema a monotonically increasing schemaVersion and tagging every persisted webhook event with the version that was current when the event was received. A version‑aware transformer then applies the correct mapping before updating downstream state.

Why this works

• Webhook payloads carry the full, current custom field definition, so the integration can reconstruct the exact schema that generated the event.
• Field IDs and option IDs are immutable, providing a stable key for mapping even when display strings change.
• Because Trello offers no dead‑letter queue or replay, buffering payloads until the referenced schema version is available guarantees that no event is lost or mis‑interpreted.

Practical Steps for Your Integration

1. Cache the schema when the webhook first arrives: store fieldId → {type, options} and assign a schemaVersion (e.g., incrementing integer).
2. Tag each webhook record with the schemaVersion that was current at receipt time. Include the action ID as an idempotency key.
3. Buffer events for a short window (e.g., 2–5 minutes). During this time, keep the schema snapshot in memory or a fast cache.
4. Process events through a transformer that looks up the payload’s schemaVersion, applies the correct field mapping, and writes the result to downstream state.
5. Handle out‑of‑order delivery by keeping the last seen action.id per board. If a newer event arrives before an older one, the buffer ensures the older event still sees the correct schema.
6. Reconcile periodically with a lightweight incremental fetch: GET /1/boards/{boardId}/customFieldItems?since={lastActionId}. This pulls only items changed after the last processed action, keeping you within Trello’s 300 requests/10 s rate limit.
7. Persist tombstoned schemas for at least the webhook retention period (currently 7 days). If a custom field is deleted, its old definition may still appear in historical actions.

What We Still Need to Know

To fine‑tune the buffer size and versioning strategy, could you confirm whether your integration already stores a schemaVersion alongside each webhook record?