Content Delivery API

The cache tags invalidation webhook

Once your pages carry cache tags, you need a way to invalidate them when editors change content. In implementing a caching mechanism, this is traditionally the most complex step to tackle.

Fortunately, DatoCMS handles the complex job of tracking every possible alteration in your schema, text, images, and videos for you. When any change happens, DatoCMS can immediately send a list of tags that need invalidation to your frontend through a single webhook.

Setting up the webhook

Within your Project Settings, create a new webhook. Choose the "Invalidate" event of the "Content Delivery API Cache Tags" entity as the trigger:

The requests that the webhook will send will be in this JSON format:

1
POST /your/invalidation/endpoint HTTP/1.1
2
Content-Type: application/json
3

4
{
5
  "entity_type": "cda_cache_tags",
6
  "event_type": "invalidate",
7
  "entity": {
8
    "id": "cda_cache_tags",
9
    "type": "cda_cache_tags",
10
    "attributes": {
11
      "tags": ["N*r;L", "6-KZ@", "t#k[uP"]
12
    }
13
  },
14
  "related_entities": []
15
}

Invalidation batches can be large

DatoCMS groups invalidations over a short window, so the tags array has no fixed upper bound: a bulk publish can easily produce several hundred tags in a single delivery.

Most purge APIs cap how many tags one request may carry, and rate-limit how often you can call them. Chunk the array to your provider's per-request limit, and retry on rate-limit responses. For reference, Cloudflare accepts 100 tags per purge request on Business plans.

Implementing the endpoint

The final step is to implement the endpoint that will receive incoming requests from the webhook. The task of this endpoint will be to execute cache invalidation based on the received cache tags.

The way you perform cache invalidation through tags greatly depends on the frontend framework and hosting solution you use. In some instances it's an API call, whereas some frameworks offer specific helper functions. The integration guides cover both cases with working code.

Don't forget to invalidate on deploy

When there's a cache layer above your application, content changes are not the only reason a cached page can go stale: a new version of your application will produce different HTML for the same content. Deploys are far less frequent than content changes, so a full purge of the CDN cache as the last step of your deploy pipeline is usually all you need.