Skip to content

Commit a875e2d

Browse files
ssganesh035ssganesh035
authored
Updated webhook documentation
1 parent 9e38958 commit a875e2d

File tree

1 file changed

+75
-57
lines changed

1 file changed

+75
-57
lines changed

‎15/umbraco-cms/reference/webhooks/README.md‎

Lines changed: 75 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -4,51 +4,55 @@ description: Umbraco webhooks enable seamless integration and real-time updates
44

55
# Webhooks
66

7-
Webhooks provide real-time, event-driven communication within Umbraco. Seamlessly integrated, these lightweight, HTTP-based notifications empower you to trigger instant actions and synchronize data. With its different extension points, you can tailor these webhooks to fit a broad range of requirements.
7+
Webhooks provide real-time, event-driven communication within Umbraco. They enable external services to react to content changes instantly by sending HTTP requests when specific events occur. This allows you to integrate with third-party services, automate workflows, and synchronize data effortlessly.
88

99
## Getting Started
1010

11-
To work with Webhooks, go to **Webhooks** in the **Settings** section.
11+
To manage webhooks, navigate to **Settings > Webhooks** in the Umbraco backoffice.
1212

1313
![Webhooks section](images/webhook-section-v14.png)
1414

15-
To create a webhook, click the `Create` button. It will take you to the Create webhook screen.
15+
To create a webhook, click **Create**. This opens the webhook creation screen where you can configure the necessary details.
1616

1717
![Creating a webhook](images/create-webhook-v14.png)
1818

19-
## URL
19+
## Configuring a Webhook
2020

21-
The `Url` should be the endpoint you want the webhook to send a request to, whenever a given `Event` is fired.
21+
### URL
2222

23-
## Events
23+
The `Url` is the endpoint where the webhook will send an HTTP request when the selected event is triggered. Ensure this endpoint is publicly accessible and capable of handling incoming requests.
2424

25-
Events are when a given action happens. By default, there are 5 events you can choose from.
25+
### Events
2626

27-
- Content Published - This event happens whenever some content gets published.
28-
- Content Unpublished - This event happens whenever some content gets unpublished
29-
- Content Deleted - This event happens whenever some content gets deleted.
30-
- Media Deleted - This event happens whenever a media item is deleted.
31-
- Media Saved - This event happens whenever a media item is saved.
27+
Webhooks can be triggered by specific events in Umbraco. By default, Umbraco provides the following events:
3228

33-
## Content Type
29+
| Event Name | Description |
30+
|--------------------|--------------------------------------------------|
31+
| Content Published | Fires when content is published. |
32+
| Content Unpublished | Fires when content is unpublished. |
33+
| Content Deleted | Fires when content is deleted. |
34+
| Media Deleted | Fires when a media item is deleted. |
35+
| Media Saved | Fires when a media item is saved. |
3436

35-
For Content or Media events, you can specify if your webhook should trigger only for specific Document or Media types.
37+
### Content Type Filtering
3638

37-
For example, if you have selected the `Content Published` event, you can set your webhook to trigger only for specific content types.
39+
For **Content** or **Media** events, you can specify whether the webhook should trigger for all content types or only specific ones. This is useful when you only need webhooks for certain document types, such as blog posts or products.
3840

39-
## Headers
41+
### Custom Headers
4042

41-
You can specify custom headers that will be sent with your request.
43+
You can define custom HTTP headers that will be included in the webhook request. Common use cases include:
4244

43-
For example, you can specify `Accept: application/json`, security headers, and so on.
45+
- Specifying request format: `Accept: application/json`
46+
- Adding authentication tokens: `Authorization: Bearer <your-token>`
47+
- Including security headers
4448

45-
## Defaults
49+
## Default Behavior of Umbraco Webhooks
4650

47-
Umbraco webhooks are configured with some defaults, such as default headers or some events that send a payload. In this section, we will take a look at those.
51+
Umbraco webhooks come with predefined settings and behaviors.
4852

49-
### JSON payload
53+
### JSON Payload
5054

51-
For example, the `Content Published` event sends the specific content that triggered the event. The JSON format is identical to the `Content Delivery API`. Here’s an example of a JSON object:
55+
Each webhook event sends a JSON payload. For example, the `Content Published` event includes full content details:
5256

5357
```json
5458
{
@@ -68,27 +72,29 @@ For example, the `Content Published` event sends the specific content that trigg
6872
}
6973
```
7074

71-
However, the `Content deleted` does not send the entire content as JSON, instead, it sends the `Id` of the content:
75+
In contrast, the `Content Deleted` event sends only the content ID:
7276

7377
```json
7478
{
7579
"Id": "c1922956-7855-4fa0-8f2c-7af149a92135"
7680
}
7781
```
7882

79-
### Headers
83+
### Default Headers
8084

81-
By default, webhook requests includes 3 headers:
85+
Webhook requests include the following headers by default:
8286

83-
- `user-agent: Umbraco-Cms/{version}` - where version is the current version of Umbraco.
84-
- `umb-webhook-retrycount: {number of retries}` - where number of retries is the current retry count for a given webhook request.
85-
- `umb-webhook-event: {Umbraco.event}` - where event is the event that triggered the request. For example, for Content published: `umb-webhook-event: Umbraco.ContentUnpublish`
87+
| Header Name | Description |
88+
|-------------|-------------|
89+
| `user-agent: Umbraco-Cms/{version}` | Identifies the Umbraco version sending the webhook. |
90+
| `umb-webhook-retrycount: {number}` | Indicates the retry count for a webhook request. |
91+
| `umb-webhook-event: {event}` | Specifies the event that triggered the request. Example: `umb-webhook-event: Umbraco.ContentPublished`. |
8692

87-
## Configuring Webhooks
93+
## Extending Webhooks
8894

89-
### Adding Events
95+
### Adding Custom Events
9096

91-
To add more than the default events to Umbraco, you can leverage the provided `IUmbracoBuilder` and `IComposer` interfaces. Below is an example of how you can extend the list of available webhook events using a custom `WebhookComposer`:
97+
You can extend the list of webhook events using `IUmbracoBuilder` and `IComposer`. Here’s an example of how to add custom webhook events:
9298

9399
```csharp
94100
using Umbraco.Cms.Core.Composing;
@@ -101,7 +107,7 @@ public class CustomWebhookComposer : IComposer
101107
.Clear()
102108
.AddCms(cmsBuilder =>
103109
{
104-
// Add your custom events here
110+
// Add custom events
105111
cmsBuilder
106112
.AddDefault()
107113
.AddContent()
@@ -124,17 +130,15 @@ public class CustomWebhookComposer : IComposer
124130
}
125131
```
126132

127-
This is a list of all the current events that are available through Umbraco. If you want them all enabled, use the following:
133+
To enable all available events, use:
128134

129135
```csharp
130136
builder.WebhookEvents().Clear().AddCms(false);
131137
```
132138

133-
## Replace Webhook Events
139+
### Replacing Webhook Events
134140

135-
Sometimes it is desirable to modify one of the standard Umbraco webhooks, for example, to change the Payload. This can be done by adding a custom implementation, as shown in the code example below:
136-
137-
{% include "../../.gitbook/includes/obsolete-warning-ipublishedsnapshotaccessor.md" %}
141+
You can modify existing webhook events, such as changing the payload format, by creating a custom implementation:
138142

139143
```csharp
140144
[WebhookEvent("Content Published", Constants.WebhookEvents.Types.Content)]
@@ -143,8 +147,14 @@ public class MyCustomContentPublishedWebhookEvent : WebhookEventContentBase<Cont
143147
private readonly IPublishedSnapshotAccessor _publishedSnapshotAccessor;
144148
private readonly IApiContentBuilder _apiContentBuilder;
145149

146-
147-
public MyCustomContentPublishedWebhookEvent(IWebhookFiringService webhookFiringService, IWebhookService webhookService, IOptionsMonitor<WebhookSettings> webhookSettings, IServerRoleAccessor serverRoleAccessor, IPublishedSnapshotAccessor publishedSnapshotAccessor, IApiContentBuilder apiContentBuilder) : base(webhookFiringService, webhookService, webhookSettings, serverRoleAccessor)
150+
public MyCustomContentPublishedWebhookEvent(
151+
IWebhookFiringService webhookFiringService,
152+
IWebhookService webhookService,
153+
IOptionsMonitor<WebhookSettings> webhookSettings,
154+
IServerRoleAccessor serverRoleAccessor,
155+
IPublishedSnapshotAccessor publishedSnapshotAccessor,
156+
IApiContentBuilder apiContentBuilder)
157+
: base(webhookFiringService, webhookService, webhookSettings, serverRoleAccessor)
148158
{
149159
_publishedSnapshotAccessor = publishedSnapshotAccessor;
150160
_apiContentBuilder = apiContentBuilder;
@@ -164,14 +174,14 @@ public class MyCustomContentPublishedWebhookEvent : WebhookEventContentBase<Cont
164174

165175
return new
166176
{
167-
MyData = "Your data",
177+
CustomData = "Your data",
168178
PublishedContent = publishedContent is null ? null : _apiContentBuilder.Build(publishedContent)
169179
};
170180
}
171181
}
172182
```
173183

174-
Add the following line in a Composer to replace the standard Umbraco implementation with your custom implementation:
184+
To replace the default Umbraco webhook with your custom implementation:
175185

176186
```csharp
177187
public class MyComposer : IComposer
@@ -183,24 +193,32 @@ public class MyComposer : IComposer
183193
}
184194
```
185195

186-
### Webhook Settings
196+
## Webhook Settings
187197

188-
Configure Webhook settings in your `appsettings.*.json` and is in the `Umbraco::CMS` section:
198+
Webhook settings are configured in `appsettings.*.json` under `Umbraco::CMS`:
189199

190200
```json
191-
"Umbraco": {
192-
"CMS": {
193-
"Webhook": {
194-
"Enabled": true,
195-
"MaximumRetries": 5,
196-
"Period": "00:00:10",
197-
"EnableLoggingCleanup": true,
198-
"KeepLogsForDays": 30
199-
}
201+
"Umbraco": {
202+
"CMS": {
203+
"Webhook": {
204+
"Enabled": true,
205+
"MaximumRetries": 5,
206+
"Period": "00:00:10",
207+
"EnableLoggingCleanup": true,
208+
"KeepLogsForDays": 30
209+
}
210+
}
211+
}
200212
```
201213

202-
- **Enabled**: Specifies whether webhooks are enabled.
203-
- **MaximumRetries**: Defines the number of retries for a webhook request.
204-
- **Period**: The interval between checks for any webhook requests that need to be fired.
205-
- **EnableLoggingCleanup**: Indicates whether webhook log cleanup is enabled.
206-
- **KeepLogsForDays**: Determines the number of days to retain webhook logs.
214+
| Setting | Description |
215+
|---------|-------------|
216+
| `Enabled` | Enables or disables webhooks. |
217+
| `MaximumRetries` | Sets the maximum number of retry attempts. |
218+
| `Period` | Defines the retry interval. |
219+
| `EnableLoggingCleanup` | Enables automatic cleanup of logs. |
220+
| `KeepLogsForDays` | Determines how long webhook logs are retained. |
221+
222+
## Testing Webhooks
223+
224+
Use [Beeceptor](https://beeceptor.com/) or [RequestBin](https://pipedream.com/requestbin) to test your event trigger integrations before deploying them to production.

0 commit comments

Comments
 (0)