Webhookについて

2023年8月1日2023年8月2日

Webhook機能はβ版です。
フィールド名や値などのパラメータが変更される可能性がありますのでご了承ください。

Webhookは指定した注文ページの商品の購入またはキャンセルが発生したときに、
Webhook作成時に設定したPOST先URLにそのイベントを通知する機能です。

Webhookを利用することで手動で注文を社内管理システムへ転記するような作業が不要になります。

設定方法についてはこちらをご覧ください。

Webhookの実行タイミングについて

現在の仕様では決済完了時と決済取消時にイベントが発生し、Webhookが実行されます。

決済完了時とは、支払いが完了したタイミングを指します。
クレジットカード払いの場合は注文が成立した時点で決済完了になります。
銀行振込の場合は入金の確認が完了したタイミングで決済完了となります。

複数回払いまたは定期課金の場合は、決済ごとにイベントが発生し、Webhookが実行されます。

またWebhookはバッチで実行されるため、イベント発生から数程度のタイムラグが発生する場合があります。

リクエストについて

Webhookによるリクエストは HTTPS の POST にて行われます。
リクエストのタイムアウトまでの時間は5秒です。
タイムアウトなどの理由によりリクエストが受け取れなかった場合でもWebhookの再実行は行われません。

POSTリクエストは下記の構造を持ちます。

リクエストヘッダ

フィールド名	値
content-type	application/json
user-agent	OrangeSales-Webhook

リクエストボディ

下記の項目を持つJSONオブジェクトです。
発生したイベントに関わらず、すべてのフィールドが必ず送信されます。
未入力の場合や値が存在しない場合、値は null になります。

フィールド名	タイプ	説明
webhook_id	文字列	このWebhookの通知設定元のID
webhook_type	文字列	発生したイベント(※) ・決済完了時：paid ・決済取消時：cancel
webhook_date	文字列	Wehookを実行した日時
form	JSONオブジェクト	注文ページ情報
code	文字列	注文ページコード
name	文字列	注文ページ名
item	JSONオブジェクト	商品情報
code	文字列	商品コード
name	文字列	商品名
amount	数値	商品価格
order	JSONオブジェクト	注文情報
no	文字列	注文番号
date	文字列	注文日時
payment	JSONオブジェクト	決済情報
date	文字列	決済日時
amount	文字列	決済金額
method	文字列	決済方法・クレジットカード：cc ・銀行振込　　　　：jnb
method_detail	文字列	決済方法詳細・一括払い　：single ・複数回払い：virtual ・定期課金　：recurring
this_time_count	数値	今回決済回数・一括払いの場合は必ず1 ・複数回払いまたは定期課金の場合は何回目の決済が完了したか
total_count	数値	合計決済回数・一括払いの場合は必ず1 ・複数回払いまたは定期課金の場合はトータルの決済回数
cancel	JSONオブジェクト	決済取消情報
date	文字列	決済取消日時
amount	数値	決済取消金額
customer	JSONオブジェクト	購入者情報
id	文字列	購入者ID
sei	文字列	購入者の姓
mei	文字列	購入者の名
sei_kana	文字列	購入者のセイ
mei_kana	文字列	購入者のメイ
mail	文字列	購入者のメールアドレス
company	文字列	購入者の会社名
tel	文字列	購入者の電話番号
zip	文字列	購入者の郵便番号
pref	文字列	購入者の都道府県
addr1	文字列	購入者の住所
addr2	文字列	購入者の住所（建物名）
note	文字列	購入者の備考

リクエストボディのサンプル

{
  "webhook_id": "123",
  "webhook_type": "cancel",
  "webhook_date": "2023-07-21 16:38:55",
  "form": {
    "code": "F-dummy",
    "name": "ダミー注文ページ"
  },
  "item": {
    "code": "I-dummy",
    "name": "ダミー商品",
    "amount": 10000
  },
  "order": {
    "no": "230721-163855-536034",
    "date": "2023-07-21 16:38:55"
  },
  "payment": {
    "date": "2023-07-21 16:38:55",
    "amount": 2500,
    "method": "cc",
    "method_detail": "virtual",
    "this_time_count": "1",
    "total_count": "4"
  },
  "cancel": {
    "date": "2023-07-21 16:38:55",
    "amount": 2500
  },
  "customer": {
    "id": 456,
    "sei": "オレンジ",
    "mei": "太郎",
    "sei_kana": "オレンジ",
    "mei_kana": "タロウ",
    "mail": "orange.taro@example.com",
    "company": "株式会社オレンジスピリッツ",
    "tel": "03-1234-5678",
    "zip": "123-4567",
    "pref": "東京都",
    "addr1": "中央区日本橋本町1-22-33",
    "addr2": "オレンジビル10F",
    "note": "先着プレゼントを希望します"
  }
}

レスポンスについて

リクエストには常にステータスコード200を返してください。

※Webhookの設定方法についてはこちらをご覧ください。

管理画面の使い方

Posted by オレンジスピリッツ