We provide a Webhook feature to facilitate integration with external systems when content is modified. Settings can be configured under each API's "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:
Notifications will be sent when new content is published or existing published content is updated through the admin panel. (Excluding operations via review or scheduling)
Notifications will be sent when content changes from "Published" or "Published and Draft" to "Unpublished" or "Draft", or when changes are made to content that is "Unpublished".
The following information is required for the Webhook to Slack: Please refer to the official documentation for operations on the Slack side.
Webhook URL issued by Slack
When notifications are actually sent, they will be in the following format. The URL part will default to the admin panel URL, but it can also be changed to any desired URL in the settings.
service - The subdomain of the service to which the modified content belongs.
api - The endpoint specified during the update or deletion of the API.
id - The ID of the content. This is included only when an operation related to the content has been performed.
draftKey - The draft key (draftKey) that can be obtained from the management screen. This is included only when the content is in draft or scheduled publication status.
type - The type of change. It will be new for new additions, edit for edits, and delete for deletions. (This refers to the type of change to the data, regardless of the content's publication status.)
These values can be referenced within GitHub Actions as github.event.client_payload.
You can send changes to a specified email address when there are updates to content or the API. The sender's email address is info@microcms.io. The configuration details are as follows:
Email Address
Additionally, similar to Slack and Chatwork webhooks, the body will contain a URL, which can also be changed to any desired one.
Custom notifications send a POST request to any specified URL. Since any URL can be specified, the receiving side can perform its own processing freely.
microCMS can add a header value to verify that the webhook request is from microCMS. To do this, a secret value must be set, and it is recommended to configure this in microCMS.
The header x-microcms-signature: <COMPUTED_HASH> will only be added if a secret value is set. ※ The payload is generated by microCMS using a hash-based HMAC with SHA-256 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 for the secret value. (Example: a value generated by ruby -rsecurerandom -e 'puts SecureRandom.hex(20)')
The request header includes 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.
Information
From a security perspective, we restrict the setting of Webhooks to domains associated with microCMS (.microcms.io, .microcms-management.io).
service - The subdomain of the service to which the modified content belongs.
api - The endpoint specified during the creation or update of the API.
id - The ID of the content. For operations related to the API, null will be present.
type - The type of change. For new additions, new; for edits, edit; for deletions, delete. (This refers to the type of change to the data, regardless of the content's publication status.)
contents - Contains the content details. For operations related to the API, null will be present.
contents.old - Contains the content before editing or deletion. For new content creation, null will be present.
contents.old.id - Contains the ID of the content before editing or deletion.
contents.old.status - Indicates the publication status of the content as an array. PUBLISH for published, DRAFT for draft, and CLOSED for unpublished.
contents.old.draftKey - Contains the draft key (draftKey) that can be obtained in the management screen if the content is in draft status. If only in published status, null will be present.
contents.old.publishValue - Contains the JSON data obtained via the GET API for published content.
contents.old.draftValue - Contains the JSON data obtained via the GET API for draft content.
contents.new - Contains the content after creation or editing. For deletions, null will be present.
contents.new.id - Contains the ID of the content after creation or editing.
contents.new.status - Indicates the publication status of the content as an array. PUBLISH for published, DRAFT for draft, and CLOSED for unpublished.
contents.new.draftKey - Contains the draft key (draftKey) that can be obtained in the management screen if the content is in draft status. If only in published status, null will be present.
contents.new.publishValue - Contains the JSON data obtained via the GET API for published content.
contents.new.draftValue - Contains the JSON data obtained via the GET API for draft content.
Copy the URL obtained from devhook into the custom notification URL field.
Perform the triggering operation on the management screen and check the output on devhook.
▼ Example of Output
Caution
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. When disabled, no Webhooks will be issued.
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 apply are as follows:
In principle, Webhook notifications are sent in the order of operation execution. However, since strict control is not implemented, the order is not guaranteed.
Tips
Information
Caution