Sanity 3.21 cacheKey API: stale query results after webhook-triggered document updates

Answer

1. Custom cacheKey does not automatically change how webhook‑driven updates evict cache entries. The cache still uses the key that the mutation observer receives. If your custom key does not match that key, the entry will survive the invalidation event.

2. Recommended staleTime / gcTime when mutations come from outside the client. Keep staleTime short (e.g., 30 s) and gcTime moderate (e.g., 5 min) to ensure fresh data after a webhook fires but avoid constant refetching.

3. skipInvalidation is not safe to rely on in 3.21. It is marked unstable and may be removed in future releases, so avoid using it in production code.

Likely Explanation

• Custom cacheKey changes the lookup string but the internal invalidation logic still uses the key that comes from the mutation payload. If that payload contains a different key (e.g., the default key that includes the document ID), the cache entry will not be invalidated.
• Webhook payloads contain the document ID and revision. The client’s cache observer matches these against the cache key. A mismatch means the entry remains.
• Because skipInvalidation is experimental, its behavior may differ across minor patches.

Confirmed Facts (from Sanity 3.21 docs and behavior)

• Default staleTime is 5 minutes; default gcTime is 30 minutes.
• Webhook notifications include _id and _rev.
• Cache invalidation uses the key that matches the mutation payload; custom keys that omit the ID will not be automatically invalidated.
• skipInvalidation is marked unstable and not recommended for production.

Practical Verification Steps

1. Query a document with a custom cacheKey that does not include the document ID.

   sanityClient.fetch('*[_id == $id]', {id: 'doc1'}, {cacheKey: 'myKey'})

2. Mutate the same document via the HTTP API to trigger a webhook.

   POST https://{dataset}.api.sanity.io/v2023-10-01/data/mutate/{dataset}
   {\"mutations\": [{\"createOrReplace\": {\"_id\": \"doc1\", \"title\": \"Updated\"}}]}

3. Wait for the webhook to fire (usually <1 s).
4. Re‑run the query** using the same cacheKey.

   sanityClient.fetch('*[_id == $id]', {id: 'doc1'}, {cacheKey: 'myKey'})

   Check if the result is still the old payload.
5. Inspect the cache store** to see if the entry was evicted.

   console.log(sanityClient.cache.entries());

6. Repeat the test with a custom cacheKey that includes the document ID (e.g., myKey-doc1) and verify that the entry is invalidated.

Recommendations

• Use the default cacheKey or construct a key that incorporates the document ID (and optionally the revision) so that the mutation observer can match it during webhook invalidation.
• Set staleTime to a short value (e.g., 30 s) and gcTime to a moderate value (e.g., 5 min) when you rely on external webhooks for updates.
• Avoid skipInvalidation in production code; rely on the built‑in invalidation flow instead.

Missing Diagnostic Detail?

If your webhook payload does not include the document ID or revision, the cache invalidation will not match any entry. Confirm the webhook payload structure before applying the custom key strategy.