Webhook headers
Overview
Every webhook request includes the following predefined headers:
Header Name | Value |
---|---|
X-Contentful-Topic |
ContentManagement.[Type].[Action] |
X-Contentful-Webhook-Name |
Webhook's name |
Content-Type |
application/vnd.contentful.management.v1+json |
Consuming services can use the X-Contentful-Topic
header to determine the type of payload included in the webhook call without looking into it. The topics depend on various actions which are described in the concepts section.
The X-Contentful-Topic
header can have the following values:
ContentManagement.ContentType.create
ContentManagement.ContentType.save
ContentManagement.ContentType.publish
ContentManagement.ContentType.unpublish
ContentManagement.ContentType.delete
ContentManagement.Entry.create
ContentManagement.Entry.save
ContentManagement.Entry.auto_save
ContentManagement.Entry.archive
ContentManagement.Entry.unarchive
ContentManagement.Entry.publish
ContentManagement.Entry.unpublish
ContentManagement.Entry.delete
ContentManagement.Asset.create
ContentManagement.Asset.save
ContentManagement.Asset.auto_save
ContentManagement.Asset.archive
ContentManagement.Asset.unarchive
ContentManagement.Asset.publish
ContentManagement.Asset.unpublish
ContentManagement.Asset.delete
ContentManagement.Task.Create
ContentManagement.Task.Save
ContentManagement.Task.Delete
ContentManagement.Comment.create
ContentManagement.Comment.save
ContentManagement.Comment.delete
ContentManagement.Release.create
ContentManagement.Release.save
ContentManagement.Release.delete
ContentManagement.Workflow.create
ContentManagement.Workflow.save
ContentManagement.Workflow.complete
ContentManagement.TemplateInstallation.complete
Other event types
ContentManagement.ReleaseAction.create
ContentManagement.ReleaseAction.execute
ContentManagement.ScheduledAction.create
ContentManagement.ScheduledAction.save
ContentManagement.ScheduledAction.delete
ContentManagement.BulkAction.create
ContentManagement.BulkAction.execute
SpaceManagement.EnvironmentAlias.create
SpaceManagement.EnvironmentAlias.change_target
SpaceManagement.EnvironmentAlias.delete
AppManagement.AppInstallation.create
AppManagement.AppInstallation.save
AppManagement.AppInstallation.delete
AppManagement.AppActionCall.call
Contextual event headers
Additionally, extra headers may be emitted to provide context for an action, such as an entry being published by a scheduled action or as part of a release.
Header name | Value |
---|---|
x-contentful-scheduled-action-id |
The sys.id of the ScheduledAction that was executed. Present only when executed via a scheduled action |
x-contentful-bulk-action-id |
The sys.id of the BulkAction that was executed. Present only when executed via a bulk action |
x-contentful-release-action-id |
The sys.id of the ReleaseAction that was executed. Present only when executed via a release action |
x-contentful-release-id |
The sys.id of the Release that contained this Entry or Asset. Present only when executed via a release action |
x-contentful-release-version |
The sys.version of the Release that contained this Entry or Asset at execution time. Present only when executed via a release action |
Consuming services can use these headers to correlate events across multiple webhook calls to group the calls into a single downstream action, such as debouncing a rebuild of a website
CRN header
When triggered by an App Action call or an App Installation, Asset, or Entry event, the X-Contentful-CRN
header is included.
This header provides the Contentful Resource Name (crn), an API identifier of the entity that triggered the webhook.
Custom headers
Besides these headers, you can configure webhooks to be called with a set of additional headers of your choice. When creating or updating a webhook, you can provide a list of headers that will be included in successive calls to that webhook.
For example assume that:
- One of your entries has just been published.
- The name of your webhook is 'Notify subscribers'.
- You have defined two custom headers,
X-Notify: subscribers
andAuthentication: subscribers
.
The webhook would be called with the following set of headers:
X-Contentful-Topic: ContentManagement.Entry.publish
X-Contentful-Webhook-Name: Notify subscribers
X-Notify: subscribers
Authentication: subscribers
Custom headers are provided with the headers
property of the Webhook Definition:
{
...,
"headers": [
{ "key": "X-Notify", "value": "subscribers" },
{ "key": "Authentication", "value": "subscribers" }
]
}
You can mark a header as secret. Value of secret headers is hidden in the web app, API responses and logs. The first time you define a secret header you need to provide its value and the secret
flag set to true
:
{
...,
"headers": [
{ "key": "X-Notify", "value": "subscribers" },
{ "key": "Authentication", "value": "subscribers", "secret": true }
]
}
Any consecutive update can omit the value
property as long as the secret
is true
. Previously provided value will be used in this scenario:
{
...,
"headers": [
{ "key": "X-Notify", "value": "updated subscribers" },
{ "key": "Authentication", "secret": true }
]
}
Header values may contain values from the original payload. See header transformations.
Header transformations
For more information on header transformations, check out the webhook transformations page.
Signed request verification headers
When you've configured a webhook signing secret in the webhook settings of your space, a signature will be generated for all webhook requests coming from events in that space. When a consuming service receives a request, it can compute a signature in the same way. If the secret is the same, the signatures will match too, thus verifying that the sender knows the secret. For this reason, it is also important to not share the secret with any third party.
This signature and some additional metadata is then added to the headers of the request before it is sent. The headers look like this:
Header name | Value |
---|---|
x-contentful-signature |
The computed signature of an individual request. |
x-contentful-signed-headers |
A comma-separated list of headers included in the computed signature. |
x-contentful-timestamp |
Timestamp of when the request was signed. Can be used to ensure a TTL and avoid processing stale or replayed events. |
Consuming services can use these headers to verify the authenticity and integrity of incoming webhooks. See verifyRequest in node-apps-toolkit for more information.