【Webhook】通知を受け取るシステムを実装する – カラーミーショップ　ヘルプセンター

Webhookで送信される通知を受け取るシステムを実装する方向けの技術情報です。管理画面での設定方法は【Webhook（外部システムへの通知）】をご覧ください。

なお、本機能およびAPIに関する技術的なサポートは行っておりませんため、実装はご自身でお願いいたします。

仕様

リクエスト

管理画面で登録したURLに対して、次の形式でリクエストを送信します。

項目	内容
メソッド	POST
Content-Type	application/json

通知の形式と署名はStandard Webhooksの仕様に準拠しています。

ヘッダー

ヘッダー	内容
`webhook-id`	通知を識別するID。同じ通知が再送された場合も同じ値になります
`webhook-timestamp`	送信時刻のUNIX時間（秒）
`webhook-signature`	署名。`v1,` に続けてBase64でエンコードした値が入ります

ペイロード

受注が作成されたとき（「受注したとき」）の通知では、次のペイロードを送信します。

{
  "id": "018f2d3b-9a7e-7c4f-89ab-1234567890ab",
  "type": "sale.created",
  "timestamp": "2026-09-01T10:15:30+09:00",
  "data": {
    "sales_id": 123456,
    "account_id": "PA12345678"
  }
}

フィールド	型	内容
`id`	string	通知を識別するID。`webhook-id` ヘッダーと同じ値です
`type`	string	イベントの種類。受注が作成されたときは `sale.created` です
`timestamp`	string	イベントが発生した時刻（ISO 8601形式）
`data.sales_id`	integer	受注ID。受注APIのレスポンスの `id` と同じ値です
`data.account_id`	string	ショップを識別するアカウントID

注文者の氏名や住所などの情報は含まれません。受注の内容は、受け取った sales_id を使って GET https://api.shop-pro.jp/v1/sales/{sale_id} から取得します。

利用方法

署名を検証する

届いた通知がカラーミーショップから送信されたものであることを、署名で確認します。検証にはStandard Webhooksの公式ライブラリを利用できます。JavaScriptの場合は次のように記述します。

import { Webhook } from "standardwebhooks"

// 管理画面で発行した whsec_ から始まる文字列をそのまま渡します
const wh = new Webhook(process.env.COLORME_WEBHOOK_SECRET)

// 検証に失敗した場合は例外が発生します
wh.verify(rawBody, headers)

検証にあたっては次の点にご注意ください。

受信した生のボディの文字列で検証してください。JSONをパースして再度文字列に変換した値では、署名の対象と1バイトでも異なると検証に失敗します
webhook-timestamp には5分の許容時間があります。受信後すみやかに検証してください
通知を受け取るサーバーの時計をNTPなどで同期してください。時計が許容時間を超えてずれていると、正しい署名でも検証に失敗します

公式ライブラリはJavaScript・TypeScriptのほか、Python・Ruby・Go・PHP・Java・Kotlin・C#・Rust・Elixir向けにも提供されています。

通知に応答する

通知を受け取ったら、時間のかかる処理は後続に回し、まずステータスコード2xxを返してください。応答がない場合、同じ通知が再送されることがあります。

通知の送信が繰り返し失敗する通知先は、登録を削除する場合があります。応答できない状態が続かないよう、受信側の可用性にご注意ください。

同じ通知を二重に処理しないようにする

同じ内容の通知が複数回届くことがあります。処理済みの webhook-id を記録しておき、すでに処理した通知は読み飛ばす実装にしてください。

通知の取りこぼしを補完する

通知は、イベントが発生したという事実を伝えるものです。ネットワークの状況や受信側の状態によって届かないことがあるため、受注の作成の通知については、受注一覧APIと定期的に照合する実装を推奨します。

前回照合した時刻から数分のマージンを引いた時刻を、照合する期間の開始点にします
GET https://api.shop-pro.jp/v1/sales に update_date_min と update_date_max を指定して、照合する期間を区切ります
limit（最大100）と offset を使って、期間内のすべてのページを取得します
通知で処理済みの受注は、webhook-id と同じ考え方で二重に処理しないようにします

照合にあたっては次の点にご注意ください。

受注の作成・入金・発送・キャンセル・金額の変更は、更新日時が変わるため差分に含まれます
配送先住所・追跡番号・備考など受注の周辺情報だけを変更した場合は、更新日時が変わらないため差分に含まれません

よくある質問

Q. 署名の検証に失敗します。どうすればよいですか？

次の点をご確認ください。

受信した生のボディで検証しているか
管理画面に表示されているシークレットと一致しているか（whsec_ から始まる文字列をそのまま指定します）
通知を受け取るサーバーの時計がずれていないか

Q. 受注の内容はどのように取得しますか？

GET https://api.shop-pro.jp/v1/sales/{sale_id} から取得します。APIの利用にはアクセストークンが必要です。APIの概要は「APIでできること」を、APIの仕様は「カラーミーショップ API ドキュメント」をご確認ください。

Q. 受注の作成以外の通知は受け取れますか？

現在通知の対象になるのは、受注が作成されたタイミングのみです。

▶︎ 関連マニュアル

仕様