Introduction

Contentful webhooks are powerful tools for reacting to content changes in real-time. By default, they send a standard payload, but what if your integration needs just specific data, or a different structure altogether?

Their is a great Contentful article on webhooks (where I borrowed the image from)

In this post, I’ll explore how to use custom webhook payloads in Contentful to better control what data is sent and how it’s formatted – ideal for APIs, automations, and microservice-based architectures.

Why Use a Custom Payload?

Default webhook payloads can be large or not structured in the way your consumer expects. Custom payloads allow you to:

• Minimize data to reduce payload size.
• Format JSON for compatibility with external systems.
• Include only relevant fields or metadata.
• Avoid needing to write translation logic in your receiving service.

Example

Let’s say you want to notify an endpoint when a new blog post is published, but only send the title, slug and the tags.

1: Create a Webhook in Contentful

Go to Settings → Webhooks → Add Webhook

• Name: Search Index Sync
• URL: http://api.com/endpoint
• Triggers (choose what you want but common ones are):
  • Entry published
  • Entry unpublished
  • Entry deleted

2: Define a Custom Payload

Scroll to the “Custom payload” section and enable it.

Paste the following sample custom payload:

{
  "id": "{{sys.id}}",
  "title": "{{fields.title.en-US}}",
  "slug": "{{fields.slug.en-US}}",
  "tags": "{{fields.tags.en-US}}",
  "updatedAt": "{{sys.updatedAt}}",
  "environment": "{{sys.environment.sys.id}}",
  "eventType": "{{sys.type}}"
}

You can use Contentful’s template syntax to inject values. This gives you access to loads of options.

You can also add static keys like api keys or custom headers

3: Receiving the Webhook

Basically trigger the webhook by performing the action. There is log viewer showing the status of every request.

This normally presents error information and shows the success rate of the triggered webhook.

Advanced Tips

1. Include Conditional Fields

You can use Handlebars-style conditionals in the payload like:

"heroImage": "{{#if fields.heroImage.en-US}}{{fields.heroImage.en-US.sys.id}}{{/if}}"

2. Use Secrets or Tokens

Secure your endpoint using:

• Custom headers
• HMAC signatures (Contentful supports this)
• IP whitelisting

3. Support Multiple Environments

Include the environment or space ID in the payload to help route or filter in your receiving app.

Real-World Scenarios

Use Case	Payload	Endpoint
Search Indexing	Minimal, only public fields	/update-index
Slack Notifications	Title + author + publish time	Slack webhook URL
CRM Update	Name, email, company	CRM API

Conclusion

Custom webhook payloads give you the power to tailor integrations precisely to your needs – reducing friction, improving performance, and simplifying downstream processing.

Whether you’re triggering deployments, syncing content, or sending alerts, taking control of the webhook payload structure helps ensure your integration stack stays lean and robust.