We provide a Webhook feature to integrate with external systems when content changes occur.
Settings can be configured in each API under "API Settings" → "Webhook".
Please select the type of Webhook from the add button and configure it.
The following 9 types of Webhooks can be configured:
You can set the timing for issuing Webhooks when configuring each Webhook.
Notifications will be sent when content becomes "Published" or when changes occur to content that is "Published" or "Published and Draft".
Notifications will be sent when new content is published or existing published content is updated through the Administration Console. (Excluding operations via review or scheduling)
Notifications will be sent in the following cases:
Notifications will be sent when new content is published or existing published content is updated through the review request feature.
Notifications will be sent when new content is published or existing published content is updated through the scheduled publication feature.
Notifications will be sent when published content is reordered in the contents list screen.
Notifications will be sent when the content ID of published content is updated.
Notifications will be sent when the publication date of published content is updated.
Notifications will be sent when the custom status of published content is updated.
Notifications will be sent when content changes from "Published" or "Published and Draft" to "Publication Ended" or "Draft", or when changes occur to content that is "Publication Ended".
Notifications will be sent in the following cases:
Notifications will be sent when "Published" or "Published and Draft" content is changed to "Publication Ended" through the scheduled publication end feature.
Notifications will be sent when "Publication Ended" content is reordered in the contents list screen.
Notifications will be sent when the content ID of "Publication Ended" content is updated.
Notifications will be sent when the publication date of "Publication Ended" content is updated.
Notifications will be sent when the custom status of "Publication Ended" content is updated.
Notifications will be sent when content becomes "Draft" or "Published and Draft", or when changes occur to content that is "Draft".
Notifications will be sent when "Draft" content is updated through the Administration Console.
Notifications will be sent in the following cases:
Notifications will be sent when "Draft" content is reordered in the contents list screen.
Notifications will be sent when the content ID of "Draft" content is updated.
Notifications will be sent when the publication date of "Draft" content is updated.
Notifications will be sent when the custom status of "Draft" content is updated.
Notifications will be sent when "Published" or "Published and Draft" content is deleted.
Notifications will be sent when "Published" or "Published and Draft" content is deleted through the Administration Console.
Notifications will be sent when "Published" or "Published and Draft" content is deleted via DELETE API.
Notifications will be sent when "Publication Ended" content is deleted.
Notifications will be sent when "Publication Ended" content is deleted through the Administration Console.
Notifications will be sent when "Publication Ended" content is deleted via DELETE API.
Notifications will be sent when "Draft" content is deleted.
Notifications will be sent when "Draft" content is deleted through the Administration Console.
Notifications will be sent when "Draft" content is deleted via DELETE API.
Notifications will be sent when the draft of "Published and Draft" content is discarded through the Administration Console.
Notifications will be sent when changes are made to API settings (basic settings, schema, etc.).
Notifications will be sent when an API is deleted.
The following information is required for the Webhook to Slack.
For operations on the Slack side, please refer to the official documentation.
When notifications are actually sent, they will be in the following format.
The URL part will default to the Administration Console URL, but it can also be changed to any desired URL in the settings.
The following information is required for the Webhook to Chatwork.
The notification content will be the same as for Slack.
You can start the build process via Webhook from microCMS.
The configuration details are as follows:
You can start the build process via Webhook from microCMS.
The configuration details are as follows:
You can start the build process via Webhook from microCMS.
The configuration details are as follows:
You can start the build process via Webhook from microCMS.
The configuration details are as follows:
You can start the build process via Webhook from microCMS.
For detailed instructions on how to configure GitHub Actions, please refer to the help article "【Webhook Integration for Content】How to Configure GitHub Actions".
When the token expires, please obtain a new token and overwrite the value to set it again.
The request body when calling the dispatch event includes information about event_type and client_payload.
{
"event_type": "microcms_build",
"client_payload": {
"service": "your_service",
"api": "news",
"id": "RX252Zoo7",
"draftKey": "2Jnt22mLh5",
"type": "new"
}
}event_type contains the value specified for the trigger event name.
This value can be referenced as github.event.action within GitHub Actions.
client_payload contains information about the targeted content and API.
{
"service": "your_service",
"api": "news",
"id": "RX252Zoo7",
"draftKey": "2Jnt22mLh5",
"type": "new"
}Item | Description |
|---|---|
| The subdomain of the Service to which the modified Content belongs. |
| The Endpoint specified during the update or deletion of the API. |
| The Content ID. This is included only when an operation related to the Content has been performed. |
| The Draft Key ( |
| The type of change. It will be |
These values can be referenced as github.event.client_payload within GitHub Actions.
You can send changes to the specified email address when there are modifications to the content or API.
The sender's email address is info@microcms.io.
The settings are as follows:
Additionally, similar to Slack and Chatwork Webhooks, the body will contain a URL, which can also be changed to any desired one.
A POST request will be sent to a specified URL.
The settings are as follows:
Custom notifications send a POST request to any specified URL.
You can specify any URL, allowing the receiving end to handle the request as needed.
microCMS can add a header value to verify that the Webhook request is from microCMS.
To do this, you need to set a secret value, which is recommended by microCMS.
The header x-microcms-signature: <COMPUTED_HASH> will only be added if a secret value is set.
Note: The payload is generated using SHA-256 based HMAC from the secret value and the request body.
The secret value can be changed in the custom notification settings screen.
Please set a value that is difficult to guess (e.g., a value generated by ruby -rsecurerandom -e 'puts SecureRandom.hex(20)').
You can verify by comparing the following two values to confirm that the request is from microCMS.
x-microcms-signature headerrequest.body) and the set secret valueAs an example, in Node.js, verification can be implemented as follows.
const crypto = require('crypto');
const expectedSignature = crypto
.createHmac('sha256', <set secret>)
.update(request.body)
.digest('hex');
const signature = request.headers['x-microcms-signature'];
if (typeof signature !== 'string') {
throw new Error('Invalid signature.');
}
const signatureBuffer = Buffer.from(signature);
const expectedSignatureBuffer = Buffer.from(expectedSignature);
if (
signatureBuffer.length !== expectedSignatureBuffer.length ||
!crypto.timingSafeEqual(signatureBuffer, expectedSignatureBuffer)
) {
throw new Error('Invalid signature.');
}The request headers will include Content-Type: application/json.
If the aforementioned secret is set, x-microcms-signature: <SIGNATURE_VALUE> will also be included.
You can also add any custom request headers. Please click the “+” button in Custom Request Headers to add them.
For security reasons, we restrict the setting of Webhooks to domains under microCMS (.microcms.io, .microcms-management.io).
The request body contains information about the targeted content and API.
{
service: 'webhook-test',
api: 'news',
id: 'x2xkcwog9521',
type: 'edit',
contents: {
old: {
id: 'x2xkcwog9521',
status: ['DRAFT'],
draftKey: 'Vyf_XTclTY',
publishValue: null,
draftValue: {
id: 'x2xkcwog9521',
createdAt: '2021-06-02T05:56:24.513Z',
updatedAt: '2021-06-02T06:05:09.601Z',
publishedAt: '2021-06-02T06:05:09.601Z',
revisedAt: '2021-06-02T06:05:09.601Z',
title: 'This is the title',
},
},
new: {
id: 'x2xkcwog9521',
status: ['PUBLISH'],
draftKey: null,
publishValue: {
id: 'x2xkcwog9521',
createdAt: '2021-06-02T05:56:24.513Z',
updatedAt: '2021-06-02T06:05:09.601Z',
publishedAt: '2021-06-02T06:05:09.601Z',
revisedAt: '2021-06-02T06:05:09.601Z',
title: 'This is the title',
},
draftValue: null,
},
},
}Item | Description |
|---|---|
| The subdomain of the Service to which the modified Content belongs. |
| The Endpoint specified when creating or updating the API. |
| The Content ID. For operations related to the API, |
| The type of change. For new additions, |
| The Content details. For operations related to the API, |
| Contains the content before editing or deletion. For new Content creation, |
| Contains the |
| Indicates the publication status of the Content as an array. |
| If the Content is in draft status, this will contain the draft key (draftKey) that can be obtained from the Administration console. If only in published status, |
| Contains the JSON data obtained via the GET API for published Content. |
| Contains the JSON data obtained via the GET API for draft Content. |
| Contains the content after creation or editing. For Content deletion, |
| Contains the |
| Indicates the publication status of the Content as an array. |
| If the Content is in draft status, this will contain the draft key (draftKey) that can be obtained from the Administration console. If only in published status, |
| Contains the JSON data obtained via the GET API for published Content. |
| Contains the JSON data obtained via the GET API for draft Content. |
When verifying and debugging custom notifications, it is useful to use webhook testing tools such as "Webhook.site".
▼ Example of Output
The validation tools mentioned above are external services, so information such as the request body will be shared externally. Please be careful not to use any data that should not be leaked.
If you want to temporarily enable or disable the Webhook settings, you can do so by toggling the switch in the Webhook list. If disabled, no Webhooks will be issued.
No retry processing will be performed if the Webhook notification fails due to network errors or 4xx/5xx errors.
Webhook notifications will be sent only once per configured timing.
If multiple contents are deleted or their statuses are changed, notifications containing the request body will be executed for each of the affected contents.
The types of notifications that will be affected are as follows:
In principle, Webhook notifications will be sent in the order of operation execution.
However, since strict control is not implemented, the order is not guaranteed.
The source IP address of the Webhook is a dynamic IP address.
Additionally, the range of IP addresses is not publicly disclosed.