microCMS

メディアのWebhookを設定

最終更新日:2023年10月11日

メディアを変更(作成/更新/削除)したタイミングでWebhook通知を行うことができます。
「メディア管理」→「メディア設定」から設定可能です。


Webhookのタイミング

各Webhookの設定時にWebhookを発行するタイミングを設定できます。


メディアの作成時

メディアを新規作成(新規アップロード)したときに通知を行います。

メディアの更新時

メディアを再アップロードしたとき/ファイル名を変更したときに通知を行います。

メディアの削除時

メディアを削除したときに通知を行います。

Webhook通知について

メディアのWebhook通知では任意のURLに対してPOSTリクエストを送信します。
あらゆるURLを指定可能ですので、リクエストを受け取った側は独自の処理を行うことが可能です。

リクエスト内容

ヘッダ

リクエストヘッダには Content-Type: application/json が含まれます。

ボディ

リクエストボディには対象となったコンテンツやAPIの情報が含まれます。

{
  service: 'someId',
  type: 'new',  // new または update または delete
  old: {
    url: 'https://images.microcms-assets.io/assets/xxxx',
    width: 100,
    height: 100,
  },
  new: {
    url: 'https://images.microcms-assets.io/assets/xxxx',
    width: 100,
    height: 100,
  },
}
  • service - 変更のあったコンテンツが属するサービスのサブドメインが入ります。
  • type - 変更の種類です。新規追加時はnew、編集時はedit、削除時はdeleteが入ります。

old

メディアの編集前もしくは削除前の内容が含まれます。メディアの新規作成時にはnullが入ります。

  • old.url - メディアのurlが含まれます。
  • old.width - メディアのwidthが含まれます。画像以外のファイルの場合はnullが入ります。
  • old.height - メディアのheightが含まれます。画像以外のファイルの場合はnullが入ります。

new

メディアの作成後もしくは編集後の内容が含まれます。メディアの削除時にはnullが入ります。

  • new.url - メディアのurlが含まれます。
  • new.width - メディアのwidthが含まれます。画像以外のファイルの場合はnullが入ります。
  • new.height - メディアのheightが含まれます。画像以外のファイルの場合はnullが入ります。

セキュリティについて

microCMSからの通知を受け取るサーバは一般公開をしておく必要があります。
そのため一般的には第三者からPOSTリクエストを受ける可能性も考慮した対応を行う必要があります。

具体的にはURLの設定時に?auth=XXX などmicroCMSと受け取り側サーバにしか知り得ない値を設定しておき、
受け取り側のサーバでこの値が正しいかどうか(≒microCMSからのリクエストであるか否か)検証を行ってください。

informationInformation

microCMS側でWebhookリクエストのヘッダに署名値(Signiture)を付与する対応について検討を進めています。
恐れ入りますが、この機能が実装されるまでは上記のパラメータ対応にて第三者からのリクエストを防ぐような形にてご対応をお願いいたします。

tipsTips

Webhookで送られてくる値の検証については、「コンテンツのWebhookを設定」のページ内にてご案内しておりますので、こちらも併せてご参照ください。