【予告】受注が作成されたときに外部サービスへ通知する Webhook を提供します

2026/08/06

2026年9月に、受注が作成されたタイミングで外部サービスへ通知する Webhook の提供を予定しています。受信側の実装をご検討いただけるよう、現時点で想定している技術仕様を先行してご案内します。

初回に対応するイベントは sale.created (受注作成) のみです。そのほかのイベントへの対応は、提供開始後に順次検討します。

初回の提供は、自社で Webhook を利用したい事業者さまが、ご自身で用意した受信環境で通知を受け取る利用を想定しています。

想定する受信側の実装の流れ

通知を受け取るエンドポイントをご用意ください
管理画面から、通知を受け取るイベントと通知先 URL を登録します。登録すると署名検証用のシークレットが表示されます
通知を受け取ったら、シークレットを使って署名ヘッダを検証します
ペイロードの data.sales_id をもとに、必要な情報を取得します

通知の内容

通知の本文は、イベントによらず共通の id / type / timestamp と、イベントごとに内容が変わる data で構成します。Standard Webhooks に準拠した構造です。

{
  "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	イベントを一意に識別する ID。`webhook-id` ヘッダと同じ値です	string
type	イベントの種類。初回は `sale.created` のみです	string
timestamp	イベントの発生日時。ISO 8601 形式 (日本時間) です	string
data	イベントごとの情報。内容はイベントによって変わります	object

sale.created の data

受注が作成されたときに通知します。

キー名	値	形式
sales_id	受注 ID。受注データ取得 API の `id` と同じ値です	integer
account_id	ショップのアカウント ID。受注データ取得 API の `account_id` と同じ値です	string

data に含まれるのは受注 ID とアカウント ID のみで、金額・商品明細・購入者情報などは含まれません。必要な情報は、受注データの取得を利用いただく (※) 想定です。

※ 受注データの取得 (GET /v1/sales/:id) の利用には read_sales スコープの認可が必要です

署名の検証

通知には webhook-id / webhook-timestamp / webhook-signature の3つのヘッダを付与する予定です。Standard Webhooks に準拠しているため、Standard Webhooks 準拠のライブラリでそのまま検証いただけます。

検証に使うシークレットは通知先ごとに発行され、登録した管理画面で表示される想定です。

通知先の登録

通知先の登録は、ショップオーナーさまが管理画面から行います。通知を受け取るイベントと通知先 URL を登録すると、署名検証用のシークレットが表示されます。

通知先には、ショップオーナーさまご自身で管理されているシステムを登録することを推奨します。

提供開始の時点では、この管理画面からの登録のみに対応します。デベロッパーさまがアプリから通知先を登録し、アプリ側で通知を受け取る仕組みは、今後の提供を検討しています。

登録できる通知先は、1つのショップにつき3件までを予定しています。

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

重複した通知の扱い

通知の再送により、同じ通知が複数回届く場合があります。id が同じ通知は同一のイベントを表すため、id で処理済みかどうかを判定いただく想定です。

受注データの取得 API との併用

通知は、通知先が応答できない場合などに届かないことがあります。受注を取りこぼせない処理では、Webhook を唯一の経路にせず、受注データのリストを取得との併用をご検討ください。

update_date_min / update_date_max で期間を指定すると、その期間に作成または更新された受注を取得できます。定期的に呼び出し、通知を受け取って処理済みの受注と突き合わせることで、通知が届かなかった受注に気づけます。

注意事項

本お知らせ記載の仕様は現時点 (2026年8月6日) で想定している仕様になります。正式リリースまでに変更となる場合もございますのでご留意ください