Migration guidelines for legacy webhooks

March 24, 2025

Jan Cerman

9 minutes

Webhooks

Download PDF

The legacy webhooks are nearing their end of life. If your apps or projects rely on legacy webhooks, follow these guidelines to learn about the differences between legacy and default webhooks and transition smoothly. We recommend you migrate soon.

Migration recommendations

Understand the differences between legacy and default webhooks.
- Legacy webhooks observe changes in objects and their dependencies, default webhooks observe direct changes in individual objects.
- The events that can trigger a notification overlap between legacy and default webhooks but are not the same. Default webhooks have more granular events but some legacy events don’t have their counterparts. See legacy webhook event mapping.
Set up new webhooks in your projects to match your legacy webhooks.
- Default webhooks give you more granular control and flexibility than legacy webhooks.
- You can use filters to observe changes in specific types of content items, specific taxonomy groups, and more.
Update your apps so they process new events.
- Ensure your endpoints are prepared to handle the new webhook payloads and event types.
- Check that your endpoints correctly process the new webhook payloads.
- Make adjustments based on your tests and ensure all edge cases are covered.

Handle object dependencies

Legacy webhooks observe changes in objects and their dependencies, default webhooks observe direct changes in individual objects.

Object dependencies in legacy webhooks

With legacy webhooks, notifications are triggered when changes are observed in content items and their dependencies, such as assets, content types, and taxonomies.

Example A: Content type change

When you change a content type, the notification contains all content items based on the content type.

JSON

{
  "data": {
    "items": [
      {
        "id": "f1e95fb5-6501-5cd3-b183-f330804d3aa6",
        "codename": "article_1",
        "language": "default",
        "type": "article",
        "collection": "default"
      },
      {
        "id": "ab6d9b32-087d-5586-ac83-d97398bb4ec3",
        "codename": "article_2",
        "language": "default",
        "type": "article",
        "collection": "default"
      },
      {
        "id": "7012ecdf-52af-5be0-8f25-14a1b0667aae",
        "codename": "article_3",
        "language": "default",
        "type": "article",
        "collection": "default"
      }
    ],
    "taxonomies": []
  },
  "message": {
    "id": "c8a41abb-e3a2-4c7e-9248-415c48dc4e6c",
    "project_id": "195a50c1-f1b8-0066-9eb4-83f7246d5459",
    "type": "content_type",
    "operation": "upsert",
    "api_name": "delivery_production",
    "created_timestamp": "2024-07-11T07:10:50.1911420Z",
    "webhook_url": "https://example.com/your-webhook-endpoint"
  }
}

When a heavily used content type is changed, you get a single notification about all the content items based on the content type. This behavior can lead to large notifications and performance issues in your webhook endpoint.

Example B: Content item publish

When you publish a content item, the legacy webhook notification tells you which item was published.

JSON

{
  "data": {
    "items": [
      {
        "id": "e5d575fe-9608-4523-a07d-e32d780bf92a",
        "codename": "published_article",
        "collection": "default",
        "language": "en-US",
        "type": "article"
      }
    ],
    "taxonomies": []
  },
  "message": {
    "id": "e1b372a2-1186-4929-b370-904c59f060b7",
    "project_id": "bf32e7ab-85c3-0073-47b9-90838a8462de",
    "type": "content_item_variant",
    "operation": "publish",
    "api_name": "delivery_production",
    "created_timestamp": "2020-05-18T10:52:33.1059256Z",
    "webhook_url": "https://example.com/cache-invalidate"
  }
}

Direct changes in default webhooks

With default webhooks, notifications are triggered when an observed object is directly changed. For assets and content items, you can use Delivery API to check content dependencies (that is where the assets or items are used) when needed. Check the following endpoints:

Example A: Content type change

When you change a content type, the webhook triggers a notification only if it’s configured for content type events. In such cases, you get a single notification about the content type change. Each entity is treated independently.

JSON

{
    "notifications": [
      {
        "data": {
          "system": {
            "id": "5568750a-d7fd-51fa-a8bb-a08940ac5395",
            "name": "Article",
            "codename": "article",
            "last_modified": "2024-07-11T07:10:48.5582695Z"
          }
        },
        "message": {
          "environment_id": "195a50c1-f1b8-0066-9eb4-83f7246d5459",
          "object_type": "content_type",
          "action": "changed",
          "delivery_slot": "published"
        }
      }
    ]
  }

When a heavily used content type is changed, you get a single notification about the content type change. You don’t get any notifications about content items based on the content type. This behavior leads to small notifications, which means it’s more efficient to process them. If you want to get a list of content items that changed due to the content type change, use Delivery API to filter content items by the content type.

Example B: Content item publish

When you publish a content item, the webhook notification tells you which item was published, including the item’s metadata in the Delivery API system properties. If you want to check the item's content dependencies (that is where the item is used), you can use Deliver API to list items that reference an item.

JSON

{
  "notifications": [
    {
      "data": {
        "system": {
          "id": "32022d85-ee58-4655-9016-e130c375820a",
          "name": "This changes everything!",
          "codename": "this_changes_everything",
          "collection": "marketing",
          "workflow": "default",
          "workflow_step": "published",
          "language": "english",
          "type": "product_update",
          "last_modified": "2024-01-08T13:54:54.3153716Z"
        }
      },
      "message": {
        "environment_id": "5f313984-9216-0158-9068-1d194f578bce",
        "object_type": "content_item",
        "action": "published",
        "delivery_slot": "published"
      }
    }
  ]
}

Legacy webhook event mapping

As you can see in the JSON code samples above, the notification payload structure is different for legacy and default webhooks. Legacy webhook notifications use the type and operation properties to specify what entity changed and how. Default webhook notifications use the object_type and action properties for these purposes. The following table describes how the legacy type and operation values map to the new object_type and action values.

Legacy `type`	Legacy `operation`	`object_type`	`action`
`asset`	`upsert`	`asset`	`changed` and `metadata_changed`
`content_item`	`upsert`	`content_item`	`metadata_changed`
`content_item_variant`	`archive`	`content_item`	`deleted`
`content_item_variant`	`change_workflow_step`	`content_item`	`workflow_step_changed`
`content_item_variant`	`restore`	`content_item`	`created`
`content_item_variant`	`publish`	`content_item`	`published`
`content_item_variant`	`upsert`	`content_item`	`created` and `changed`
`content_item_variant`	`unpublish`	`content_item`	`unpublished`
`content_type`	`upsert`	`content_type`	`changed`
`language_settings`	`upsert`	`language`	`changed`
`project`	`archive`	Not applicable	Not applicable
`project`	`restore`	Not applicable	Not applicable
`project_settings`	`upsert`	Not applicable	Not applicable
`taxonomy`	`archive`	`taxonomy`	`deleted`
`taxonomy`	`restore`	`taxonomy`	`created`
`taxonomy`	`upsert`	`taxonomy`	`metadata_changed`, `term_changed`, `term_deleted`
`workflow`	`upsert`	Not applicable	Not applicable