App Events
App events allow you to define HTTP endpoints that should be called in response to changes to your entries, content types, or assets. You can do this by creating an AppEventSubscription associated to your AppDefinition.
When you create an AppEventSubscription for an entity, you can choose which topics you want your app to be subscribed to.
The given HTTP endpoint will then be called every time that a change of this topic happens in any space that the app is installed to.
The ID of the space and environment where the change happened will be included in the request so that the receiving service knows where it came from.
To set up app events from within the Contentful web app, navigate to the events tab of your app definition in the organization settings.
Within the Events tab, you can select which topics you want your app to be subscribed to. It will look like this:
The events that an app is subscribed to can be changed at any time, and the changes will immediately affect all existing and future app installations.
The receiver of an app event can be any external service. This can be useful for propagating changes to your own services or triggering CI/CD pipelines. If you would like for the receiving server to be able to independently make changes to data in Contentful in response to app events, you can set up an app identity for it. See our guide on app identities and events for a comprehensive introduction into writing a powerful backend for your app.
Updates to an AppEventSubscription can also be made programatically through the Content Management API (CMA).
App Event Functions
Using Functions, you can filter, transform, and even directly handle app events without needing to stand up your own backend. Functions enhance the flexibility of the app event pipeline, easily supporting custom ETL and validation flows, request proxying and fanout, and myriad other usecases.
Filter functions are invoked when an app event is fired, and determine whether events proceed for further processing.
Transformation functions are invoked prior to request signing, and allow you to alter the body of the app event request.
Handler functions replace the target HTTP endpoint, meaning the app events get sent directly to your function.
After writing and uploading your function(s), link them to your AppEventSubscription to enable them. This can be accomplished by issuing a CMA request to update or subscribe to events, or from within the Contentful web app by navigating again to the events tab of your app definition in the organization settings.
Within the Events tab, you can select a filter function, a transformation function, and toggle whether you want your app events to target a URL or a handler function.
