Webhook headers

An introduction to 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.

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 and Authentication: 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.