Part I: Use Update Webhook Handlers to Update Entries in Contentstack

This blog post describes a technique that uses an entry update webhook handler to update field values in the Contentstack SaaS headless CMS. You can use this technique to validate existing data in entries, to set default values for empty fields, and otherwise to manipulate field values programmatically.

This is my simplified understanding of what happens when a Contentstack user updates (creates or saves changes to) an entry:

Contentstack commits the fields specified in the commit call with existing field values to a new version of the entry, even if no field values other than system properties such as update timestamp actually change.
Contentstack invokes any relevant webhooks *after* the commit.

In other words, every commit creates a new version and passes that version in the payload of any webhook(s) configured for that save operation. One exception is that when an entry changes workflow states, Contentstack does not create a new version or trigger webhooks.

Warning: Because all entry update operations trigger update webhooks, updating the entry that triggered an update webhook from a handler for update webhooks can result in infinite recursion.

To avoid infinite recursion that would result from commit operations invoking handlers that invoke commit operations, you store the date and time of the handler operation in a field of the entry. When the commit operation invokes the handler, if the date of the most recent update to the entry is approximately the same as the date of the update to that message field, then abort the handler.

If multiple CMS users and/or processes can update field values concurrently, users must understand that they may need to compare versions to determine whether to commit or reload content. If CMS users have an entry open when a process or another CMS user commits a change, the browser temporarily prompts the CMS user to load the new version or to compare it to the version that they had loaded before the commit that created the new version.

If the CMS user ignores the prompt and saves, Contentstack commits values that the CMS user had modified in their browser to a new version and raises webhooks. In addition to the possibility of a user overwriting a change made to the intermediary version, the values seen by the CMS user before committing are not necessarily the values stored in the CMS, which loads those values after the save operation. Users should not edit entries concurrently or must beware of the consequences, and you may want to prevent users from modifying fields managed by processes.

For example, you can use a field to display messages to CMS users. While Contentstack provides various validation features, you can use this simple technique to support validation conditions and other user messaging. In Contentstack, create a global field to store the messages and the date and time at which that field value was set (explained in the next paragraph). Configure a webhook to invoke a handler that contains the logic to sets the messaging field value.

You may want certain update webhook handlers to act only during certain workflow states.

As an alternative to setting field values, you can implement a widget to message and otherwise interact with users editing an entry. Widgets appear in the UI when editing an entry. I am not a UI developer, so from my perspective this takes more effort. I am not aware of specific capabilities or limitations for working with field values in a widget, but I suspect that they can only access committed values, not those updated in the UI but not saved. I assume that it is possible to force the UI to reload the new version of the entry after calling APIs that update fields.

Custom Widgets (contentstack.com)

Custom field types may provide another alternative. Widgets appear as visual components separate from the entry while editing it. Custom fields appear within the entry rather than separately.

Update 13.April.2021: You may want to use a workflow webhook rather than an entry update webhook.