Webhookの登録方法

Webhookを受け取るには、開発者アプリに受信URLと購読するイベントを登録します。登録は開発者ポータルの画面からもAPIからもできます。この記事では両方の手順と、テスト送信、購読イベントの変更、一時停止と削除の方法を説明します。

前提

• 開発者ポータルに登録済みのアプリ。デベロッパーAPIはスタータープラン以上で使えます
• インターネットから届く https:// の受信URL。localhost やプライベートIPアドレスは登録できません
• 画面から登録する場合：アプリを持つビジネスアカウントのオーナーであること
• APIで登録する場合：ビジネスアカウントに紐づいたアクセストークン（ビジネスアカウント向けの承認フローで取得したもの）。Webhook APIは特定のスコープを要求しません

画面とAPIでできること

受信URLはあとから変更できません。変えるときは新しいWebhookを登録し、古いものを削除します。

画面から登録する

• 開発者ポータルのアプリ一覧（/ja-JP/organizations/{organizationId}/developer/apps）で対象のアプリを開きます
• 「Webhooks」の欄の「追加」を押します
• URLを入力し、受け取りたいイベントにチェックを入れて「登録する」を押します
• 画面の上部に署名用のシークレットが表示されます。この1回しか表示されないので、ここでコピーして受信サーバーに設定します

画面にはイベントの候補がすべて並びますが、実際に送信されるのは receipt.created、order.created、order.updated です（後述）。

APIで登録する

curl -X POST https://receiptroller.io/api/v1/webhooks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/rr-webhook",
    "eventTypes": ["receipt.created"],
    "secret": "{webhook_secret}"
  }'

成功するとステータス 201 で次のレスポンスが返ります。secret はこのレスポンスにしか含まれず、あとから取得するAPIはありません。

{
  "id": "wh_xxxxxxxxxxxxxxxx",
  "clientId": "{client_id}",
  "organizationId": "{organizationId}",
  "url": "https://example.com/rr-webhook",
  "eventTypes": ["receipt.created"],
  "active": true,
  "createdAt": "2026-10-26T03:00:00.0000000Z",
  "lastDeliveredAt": null,
  "secret": "{webhook_secret}"
}

登録時のエラー

購読するイベントを選ぶ

各イベントの中身はWebhookの概要を参照してください。

テスト送信

curl -X POST https://receiptroller.io/api/v1/webhooks/test/{webhook_id} \
  -H "Authorization: Bearer {access_token}"

受信URLに test.ping イベントが1回送られ、その結果が返ります。

{
  "webhookId": "wh_xxxxxxxxxxxxxxxx",
  "httpStatus": 200,
  "success": true,
  "deliveredAt": "2026-10-26T03:01:00.0000000Z"
}

• 受信URLに届くボディの data は { "message": "This is a test ping from Receipt Roller." } です。本番のイベントと同じシークレットで署名されます
• APIの応答は、Webhookが存在すれば常に 200 です。届いたかどうかは success（受信側が 2xx を返したか）と httpStatus で判断します。httpStatus が 0 なら接続そのものに失敗しています
• テスト送信は購読イベントや有効／無効の状態に関係なく送られ、再送されず、配信ログにも残りません
• 404 は、IDが違うか、別のアプリのWebhookです

変更・一時停止・削除

購読イベントの変更と、一時停止・再開は PATCH で行います。送ったフィールドだけが変わり、eventTypes は一覧ごと置き換わります。

curl -X PATCH https://receiptroller.io/api/v1/webhooks/{webhook_id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "eventTypes": ["receipt.created", "order.created"], "active": true }'

• "active": false で一時停止、"active": true で再開します。画面の一時停止・再開ボタンも同じ操作です
• 停止中に起きたイベントは保留されず、再開してもあとから届きません
• 4回続けて配信に失敗したWebhookは自動で active: false になります。受信側を直したら同じ方法で再開します
• 削除は DELETE /api/v1/webhooks/{webhook_id}（成功すると 204）です。削除すると元に戻せません
• 登録済みWebhookの一覧は GET /api/v1/webhooks、1件の取得は GET /api/v1/webhooks/{webhook_id} です。どちらにも secret は含まれません

複数のWebhookを使う

• 1つのアプリに複数のWebhookを登録できます。同じイベントを購読しているWebhookにはすべて送られ、どのWebhookにも同じ X-RR-Delivery が付きます
• 複数のビジネスアカウントのイベントを受け取るときは、それぞれのビジネスアカウントのトークンで登録します
• 一覧・取得・変更・削除・テスト送信は、アプリが登録したすべてのWebhookが対象です（どのビジネスアカウントのトークンで呼んでも同じ一覧が返ります）

登録後の確認

• 受信URLが https:// で外部から届く
• シークレットを安全な場所に保管し、受信サーバーに設定した
• 受信サーバーで署名を検証している（署名検証とセキュリティ）
• テスト送信で success: true が返る
• X-RR-Delivery で重複を除いている
• 10秒以内に 2xx を返せる

関連ガイド

• Webhookで新しい売上を受け取り、Slackに通知する（クイックスタート）
• Webhookの概要
• 署名検証とセキュリティ
• 再送・順序・冪等性の設計
• 監視と失敗時の対応
• APIリファレンス：POST /api/v1/webhooks