平素よりmicroCMSをご利用いただき、誠にありがとうございます。
この度、Webhook機能におけるリクエスト仕様を、ドキュメントの仕様に準拠した形に統一する対応を予定しております。
ご利用方法によっては、ご利用中のサービスに影響を及ぼす可能性があるため、ご連絡いたしました。

仕様統一の内容

コンテンツのWebhook／メディアのWebhook機能における、リクエストデータの仕様を統一します。
 
背景として、現在のWebhook機能においては、Webhookの実行起因となる操作内容（例：コンテンツの公開とコンテンツの並び替え）によって、送付されるリクエストヘッダーおよびリクエストボディの内容に、一部差異が発生しています。
 
この仕様の違いについては、ほとんどのケースにおいては、問題となりません。一方で、実装者の混乱を招きうる状況となっていることから、仕様統一を行います。

影響があるサービス

以下の機能および操作を利用している場合に、影響がございます。
 
1. コンテンツのWebhook機能（一部）

通知種別
・GitHub Actions
・カスタム通知

操作タイミング
・複数コンテンツの一括削除
・複数コンテンツのステータス更新
・コンテンツの並び替え
・API削除

2. メディアのWebhook機能

通知種別
・すべて（任意のURLのみ設定可能）

操作タイミング
・すべて

影響内容

1. リクエストヘッダーが小文字で統一されます

現在は、Webhookの受信先との通信プロトコルがHTTP/1.1で処理されている場合、リクエストヘッダーがトレインケースにて送付されている場合がございます。こちらが小文字での送付に統一されます。

▼ 現在の一部のリクエストヘッダー（例）

X-Your-Apikey: apikey

▼ 統一後のリクエストヘッダー（例）

x-your-apikey: apikey

2. リクエストヘッダーの内容が統一されます

現在は、一部のリクエストヘッダーの内容に差異がありますが、内容が統一されます。

▼ 現在の一部のリクエストヘッダー（例）

accept-encoding: gzip
content-type: application/json
content-length: 1000
user-agent: Go-http-client/1.1
host: microcms.io

▼ 統一後のリクエストヘッダー（例）

host: microcms.io
accept-encoding: gzip,deflate
user-agent: node-fetch/1.0 (+https://github.com/bitinn/node-fetch)
content-length: 1000
accept: */*
content-type: application/json

3. リクエストボディのキーが、コンテンツAPIのレスポンスのキーの並びと統一されます

現在は、Webhookのリクエストボディのキーの並び順がアルファベット順となっている場合がございます。こちらがコンテンツAPIのレスポンスボディの並び順と統一されます。

▼ 現在の一部のリクエストボディ（例）

{
  "new": {
    "height": 150,
    "url": "https://images.microcms-assets.io/assets/xxxx/yyyy/media.png",
    "width": 150
  },
  "old": null,
  "service": "microcms",
  "type": "new"
}

▼ 統一後のリクエストボディ（例）

{
  "service": "microcms",
  "type": "new",
  "old": null,
  "new": {
    "url": "https://images.microcms-assets.io/assets/xxxx/yyyy/media.png",
    "width": 150,
    "height": 150
  }
}

4. フィールドのデータが空の時のデータのレスポンスが統一されます

現在は、登録のないフィールドのデータが、コンテンツAPIのレスポンスの値と異なっているケースがございます。こちらがコンテンツAPIのレスポンスにおける空値の仕様と統一されます。

▼ 現在の一部のリクエストボディ（例）

{
  "service": "microcms",
  "api": "blogs",
  "id": "test_id",
  "type": "new",
  "contents": {
    "old": null,
    "new": {
      "id": "test_id",
      "status": [
        "PUBLISH"
      ],
      "draftKey": null,
      "publishValue": {
        "category": null,
        "content": null,
        "createdAt": "2025-06-18T07:33:49.748Z",
        "eyecatch": null,
        "id": "test_id",
        "publishedAt": "2025-06-18T07:33:49.748Z",
        "revisedAt": "2025-06-18T07:33:49.748Z",
        "title": null,
        "updatedAt": "2025-06-18T07:33:49.748Z"
      },
      "draftValue": null
    }
  }
}

▼ 統一後のリクエストボディ（例）

{
  "service": "microcms",
  "api": "blogs",
  "id": "test_id",
  "type": "new",
  "contents": {
    "old": null,
    "new": {
      "id": "test_id",
      "status": [
        "PUBLISH"
      ],
      "draftKey": null,
      "publishValue": {
        "id": "test_id",
        "createdAt": "2025-06-18T07:33:49.748Z",
        "updatedAt": "2025-06-18T07:33:49.748Z",
        "publishedAt": "2025-06-18T07:33:49.748Z",
        "revisedAt": "2025-06-18T07:33:49.748Z",
        "category": null
      },
      "draftValue": null
    }
  }
} 

推奨される対応

本対応は新たな仕様への変更ではなく、ドキュメントの仕様に準拠するための統一対応となります。ほとんどのケースにおいては、特別な対応は不要です。
 
上記の「影響内容」に記載した箇所に関連する処理を行なっている場合は、対応が必要となる場合がございます。

変更予定日

2025年8月18日(月) 
※ 不具合や想定外の事項があった場合、リリース日は変更となる可能性がございます。

おわりに

本件に関してご不明点がございます場合は、お問い合わせフォームより、ご連絡ください。