From 80608a11c9e1d269b9cea61a86da36b75fafbe0c Mon Sep 17 00:00:00 2001 From: Migaroez Date: Mon, 14 Jul 2025 17:58:25 +0200 Subject: [PATCH 1/9] Add information about webhook payload types --- 16/umbraco-cms/reference/webhooks/README.md | 53 ++++++++++++++------- 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index ef38a44c816..f49d1ae388e 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -52,31 +52,50 @@ Umbraco webhooks come with predefined settings and behaviors. ### JSON Payload -Each webhook event sends a JSON payload. For example, the `Content Published` event includes full content details: +Each webhook event sends a JSON payload. The following types of payloads are available by default -```json +- Legacy: This is the current default but will be removed in a future version. It uses the payloads as they were before V16. These payloads are inconsistent and contain information that was never ment to be exposed or is superseded by newer types (int vs guid). +- Minimal: This will be the default in v17+. This version of the payloads will only contain information to indentify the resource in question. For most resources this will be it's unique identifier. Some events might require more information. For example: the payload for the document publish event will also contain all cultures that were published at that point in time. +- Extended: These are new payload types that are available for some but not all events that gives you all relevant information regarding the event. Some information, like user/member names and emails, are not part of the payloads for security/privacy concerns. In cases where an extended payload is not present for an event, the minimal will be used as fallback. + +You can change which payload type is used by + +- Changing the appsetting `Umbraco:CMS:Webhook:PayloadType`. Be aware that the system that uses this value is run before any composers. If you manipulate the `WebhookEventCollectionBuilder` in anyway then those methods will not automatically pick up this appsetting. +- Passing in the PayloadType into the `WebhookEventCollectionBuilderExtensions` methods to control which webhook events are added + +```csharp +using Umbraco.Cms.Core.Composing; +using Umbraco.Cms.Core.Webhooks; + +namespace Umbraco.Cms.Web.UI.Composers; + +// this composer clears all registered webhooks and then adds all (umbraco provided) webhooks with their extended payloads +public class AllWebhookComposer : IComposer { - "name": "Root", - "createDate": "2023-12-11T12:02:38.9979314", - "updateDate": "2023-12-11T12:02:38.9979314", - "route": { - "path": "/", - "startItem": { - "id": "c1922956-7855-4fa0-8f2c-7af149a92135", - "path": "root" + public void Compose(IUmbracoBuilder builder) + { + builder.WebhookEvents().Clear().AddCms(onlyDefault: false, payloadType: WebhookPayloadType.Extended); } - }, - "id": "c1922956-7855-4fa0-8f2c-7af149a92135", - "contentType": "root", - "properties": {} } + ``` -The `Content Deleted` event sends only the content ID: +- Manually manipulating the `WebhookEventCollectionBuilder` -```json +```csharp +using Umbraco.Cms.Core.Composing; +using Umbraco.Cms.Core.Webhooks.Events; + +namespace Umbraco.Cms.Web.UI.Composers; + +// since legacy is the default, this composer removes the old content published webhookevent and changes it with the new extended version. +public class AllWebhookComposer : IComposer { - "id": "c1922956-7855-4fa0-8f2c-7af149a92135" + public void Compose(IUmbracoBuilder builder) + { + builder.WebhookEvents().Remove(); + builder.WebhookEvents().Add(); + } } ``` From 7daa195c39aab140559afda6e95924c714932026 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Tue, 15 Jul 2025 10:25:44 +0200 Subject: [PATCH 2/9] Update 16/umbraco-cms/reference/webhooks/README.md --- 16/umbraco-cms/reference/webhooks/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index f49d1ae388e..259931f21d2 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -52,7 +52,7 @@ Umbraco webhooks come with predefined settings and behaviors. ### JSON Payload -Each webhook event sends a JSON payload. The following types of payloads are available by default +Each webhook event sends a JSON payload. The following types of payloads are available by default. - Legacy: This is the current default but will be removed in a future version. It uses the payloads as they were before V16. These payloads are inconsistent and contain information that was never ment to be exposed or is superseded by newer types (int vs guid). - Minimal: This will be the default in v17+. This version of the payloads will only contain information to indentify the resource in question. For most resources this will be it's unique identifier. Some events might require more information. For example: the payload for the document publish event will also contain all cultures that were published at that point in time. From d4a1ead00ec33c03652035185626b007228e8552 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Tue, 15 Jul 2025 10:26:15 +0200 Subject: [PATCH 3/9] Update 16/umbraco-cms/reference/webhooks/README.md --- 16/umbraco-cms/reference/webhooks/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index 259931f21d2..306d13a2acc 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -54,7 +54,9 @@ Umbraco webhooks come with predefined settings and behaviors. Each webhook event sends a JSON payload. The following types of payloads are available by default. -- Legacy: This is the current default but will be removed in a future version. It uses the payloads as they were before V16. These payloads are inconsistent and contain information that was never ment to be exposed or is superseded by newer types (int vs guid). +#### Legacy + +This is the current default but will be removed in a future version. Legacy payloads follow the format used before version 16. They are inconsistent and may include data that should not be exposed or has been superseded (e.g., use of `int` instead of `Guid`). - Minimal: This will be the default in v17+. This version of the payloads will only contain information to indentify the resource in question. For most resources this will be it's unique identifier. Some events might require more information. For example: the payload for the document publish event will also contain all cultures that were published at that point in time. - Extended: These are new payload types that are available for some but not all events that gives you all relevant information regarding the event. Some information, like user/member names and emails, are not part of the payloads for security/privacy concerns. In cases where an extended payload is not present for an event, the minimal will be used as fallback. From 55add97371dd5377fcc07f023b219df5cfc520b1 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Tue, 15 Jul 2025 10:26:23 +0200 Subject: [PATCH 4/9] Update 16/umbraco-cms/reference/webhooks/README.md --- 16/umbraco-cms/reference/webhooks/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index 306d13a2acc..374e6f5d2d4 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -57,7 +57,9 @@ Each webhook event sends a JSON payload. The following types of payloads are ava #### Legacy This is the current default but will be removed in a future version. Legacy payloads follow the format used before version 16. They are inconsistent and may include data that should not be exposed or has been superseded (e.g., use of `int` instead of `Guid`). -- Minimal: This will be the default in v17+. This version of the payloads will only contain information to indentify the resource in question. For most resources this will be it's unique identifier. Some events might require more information. For example: the payload for the document publish event will also contain all cultures that were published at that point in time. +#### Minimal + +This will become the default in version 17 and later. Minimal payloads include only essential information to identify the resource. For most events, this means a unique identifier. Some events may include additional data. For example, a document publish event also includes the list of published cultures. - Extended: These are new payload types that are available for some but not all events that gives you all relevant information regarding the event. Some information, like user/member names and emails, are not part of the payloads for security/privacy concerns. In cases where an extended payload is not present for an event, the minimal will be used as fallback. You can change which payload type is used by From 17aee2700a4246ac805b8b7e1822ae62196916c2 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Tue, 15 Jul 2025 10:26:29 +0200 Subject: [PATCH 5/9] Update 16/umbraco-cms/reference/webhooks/README.md --- 16/umbraco-cms/reference/webhooks/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index 374e6f5d2d4..13407794089 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -60,7 +60,9 @@ This is the current default but will be removed in a future version. Legacy payl #### Minimal This will become the default in version 17 and later. Minimal payloads include only essential information to identify the resource. For most events, this means a unique identifier. Some events may include additional data. For example, a document publish event also includes the list of published cultures. -- Extended: These are new payload types that are available for some but not all events that gives you all relevant information regarding the event. Some information, like user/member names and emails, are not part of the payloads for security/privacy concerns. In cases where an extended payload is not present for an event, the minimal will be used as fallback. +#### Extended + +Extended payloads include all relevant information for an event, where available. However, sensitive data, such as usernames, member names, or email addresses, is excluded for privacy and security reasons. If an extended payload is not available for an event, the system falls back to the minimal payload. You can change which payload type is used by From 77702a21dc10281896e06de22718f32ad4c9c438 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Tue, 15 Jul 2025 10:26:37 +0200 Subject: [PATCH 6/9] Update 16/umbraco-cms/reference/webhooks/README.md --- 16/umbraco-cms/reference/webhooks/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index 13407794089..f0038d1ee59 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -64,7 +64,9 @@ This will become the default in version 17 and later. Minimal payloads include o Extended payloads include all relevant information for an event, where available. However, sensitive data, such as usernames, member names, or email addresses, is excluded for privacy and security reasons. If an extended payload is not available for an event, the system falls back to the minimal payload. -You can change which payload type is used by +### Configuring Payload Types + +Payload type can be configured in several ways: - Changing the appsetting `Umbraco:CMS:Webhook:PayloadType`. Be aware that the system that uses this value is run before any composers. If you manipulate the `WebhookEventCollectionBuilder` in anyway then those methods will not automatically pick up this appsetting. - Passing in the PayloadType into the `WebhookEventCollectionBuilderExtensions` methods to control which webhook events are added From 8c04bb24df3248584acadafb920a679e43777164 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Tue, 15 Jul 2025 10:26:43 +0200 Subject: [PATCH 7/9] Update 16/umbraco-cms/reference/webhooks/README.md --- 16/umbraco-cms/reference/webhooks/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index f0038d1ee59..7939ac06a5c 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -68,8 +68,8 @@ Extended payloads include all relevant information for an event, where available Payload type can be configured in several ways: -- Changing the appsetting `Umbraco:CMS:Webhook:PayloadType`. Be aware that the system that uses this value is run before any composers. If you manipulate the `WebhookEventCollectionBuilder` in anyway then those methods will not automatically pick up this appsetting. -- Passing in the PayloadType into the `WebhookEventCollectionBuilderExtensions` methods to control which webhook events are added +- Changing the appsetting `Umbraco:CMS:Webhook:PayloadType`. Be aware that the system that uses this value runs before any composers. If you manipulate the `WebhookEventCollectionBuilder` in any way, then those methods will not automatically pick up this app setting. +- Passing in the PayloadType into the `WebhookEventCollectionBuilderExtensions` methods to control which webhook events are added. ```csharp using Umbraco.Cms.Core.Composing; From 20870df3b4a08982ec9222e2abf9f4b6b42352a8 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Tue, 15 Jul 2025 10:28:25 +0200 Subject: [PATCH 8/9] Update 16/umbraco-cms/reference/webhooks/README.md --- 16/umbraco-cms/reference/webhooks/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index 7939ac06a5c..aa27d2b32fd 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -88,7 +88,7 @@ public class AllWebhookComposer : IComposer ``` -- Manually manipulating the `WebhookEventCollectionBuilder` +- Manually manipulating the `WebhookEventCollectionBuilder`. ```csharp using Umbraco.Cms.Core.Composing; From 83d99c8c993f9d72780c3f23986a658ae2744b56 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Tue, 15 Jul 2025 10:29:58 +0200 Subject: [PATCH 9/9] Update 16/umbraco-cms/reference/webhooks/README.md --- 16/umbraco-cms/reference/webhooks/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/webhooks/README.md b/16/umbraco-cms/reference/webhooks/README.md index aa27d2b32fd..ea50ad29dd9 100644 --- a/16/umbraco-cms/reference/webhooks/README.md +++ b/16/umbraco-cms/reference/webhooks/README.md @@ -66,7 +66,7 @@ Extended payloads include all relevant information for an event, where available ### Configuring Payload Types -Payload type can be configured in several ways: +Payload type can be configured in the following ways: - Changing the appsetting `Umbraco:CMS:Webhook:PayloadType`. Be aware that the system that uses this value runs before any composers. If you manipulate the `WebhookEventCollectionBuilder` in any way, then those methods will not automatically pick up this app setting. - Passing in the PayloadType into the `WebhookEventCollectionBuilderExtensions` methods to control which webhook events are added.