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.
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 Content ID. 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 Administration console. This is included only when the Content is in Draft or Scheduled 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 changes to the Content's publication status.)
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:
Email Address
Additionally, similar to Slack and Chatwork Webhooks, the body will contain a URL, which can also be changed to any desired one.
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)').
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.
Information
For security reasons, we restrict the setting of Webhooks to domains under microCMS (.microcms.io, .microcms-management.io).
The subdomain of the Service to which the modified Content belongs.
api
The Endpoint specified when creating or updating the API.
id
The Content ID. For operations related to the API, null will be present.
type
The type of change. For new additions, new will be present; for edits, edit; and for deletions, delete. (This refers to the type of change to the data, regardless of changes to the Content's publication status.)
contents
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
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, 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 Content deletion, 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
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, 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 the testing tool into the URL field of the custom notification.
Perform the triggering action in the Administration console and check the output on the testing tool.
▼ 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. If 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 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.
Tips
Information
Caution