Webhookの設定と管理
Webサイトでイベント(顧客の支払い完了、商品の発送や到着、問い合わせフォームの送信、ドメイン認証の失敗、トラフィックの目標達成など)が発生した際、KanorioはWebhookを通じて、指定されたURLへリアルタイムにデータを送信できます。
WebhookをZapier、Make、n8n、または独自のシステムに接続することで、新規注文をGoogleスプレッドシートに自動同期したり、フォームの送信内容をチームのSlack/Discord/Telegramグループに転送したり、サポートチケットを作成したり、企業のERPやCRMとデータを同期したりすることが可能です。
受信エンドポイントを構築するエンジニアの方へ: このガイドでは、ダッシュボードの設定、イベントのサブスクリプション、再試行ルール、トラブルシューティングについて解説しています。HTTPヘッダー、
X-Kanorio-Signature検証コード、および全8イベントのJSONフィールド仕様の詳細については、Webhookイベントと署名検証を参照してください。
はじめる前に
- 場所: ダッシュボードの"Website Settings › Developer › Webhooks"に移動します。
- エンドポイント制限: すべてのプラン(無料プラン、プロプラン、ビジネスプランを含む)で、Webサイトごとに最大10個のWebhookエンドポイントを作成できます。
- ロール権限: オーナーおよび管理者のみが、エンドポイントの追加、テスト、サブスクリプションの変更、ペイロード内容の確認、手動再試行、署名キーの表示・更新を行えます。その他のチームメンバーは、エンドポイントの表示名とステータスのみを確認でき、URL、キー、配信ログは確認できません。
Webhookの追加とテスト(5ステップ)
1. 受信ツールからHTTPS URLを取得する
受信ツールを開いてWebhook受信を作成し、URLをコピーします(URLはhttps://で始まる必要があり、localhostや内部ネットワークアドレスは使用できません)。
- Zapier: 新しいZapを作成し、トリガーに「Webhooks by Zapier」を選択 → イベントに「Catch Hook」を選択し、生成されたWebhook URLをコピーします。
- Make: 新しいシナリオを作成し、最初のモジュールに「Webhooks」を選択 → 「Custom webhook」を選択し、URLをコピーします。
- n8n: 「Webhook」ノードを追加し、HTTPメソッドを
POSTに設定して、Production/Test URLをコピーします。 - 独自システム: エンジニアに、
POSTJSONリクエストを受信可能なhttps://URLを用意してもらいます。
2. Kanorioでエンドポイントを追加する
"Website Settings › Developer › Webhooks"に移動し、「Add Webhook」をクリックします。コピーしたURLを貼り付け、わかりやすい表示名(例:「Zapier Order Sync」や「Make Form Forwarding」など)を入力して、「Add Webhook」をクリックします。
3. 署名キーをコピーまたは保存する
作成後、ダッシュボードにこのエンドポイント固有の「Signature Key」(whsec_で始まる)が表示されます。
- Zapier、Make、n8nを使用する場合: これらのツールは通常、URLパスにランダムなキーを含めるため、署名検証は不要です。「Done」をクリックしてください。
- 独自サーバーを使用する場合: この署名キーをコピーし、エンジニアに渡して署名検証を実装してもらいます。リストのエンドポイントを展開して「Show」をクリックすれば再度確認でき、「Generate New Key」をクリックすればキーを更新できます。
4. 「Send Test」をクリックして接続を確認する
リストで新しく作成したエンドポイントを展開し、「Send Test」をクリックします。システムが直ちにテストイベント(team.test)を送信します。
- 画面に「Test Successful (HTTP 200, took X ms)」と表示され、Zapier/Make/サーバーでテストデータを受信できれば、接続は成功です。
- 「Send Test」は公式の配信ログには記録されず、連続失敗回数の制限にもカウントされないため、トラブルシューティング中に必要に応じて自由に使用してください。
5. サブスクライブするイベントを調整する(任意)
新しいエンドポイントは、デフォルトで「All Events」をサブスクライブするように設定されています。特定の通知(例:「注文支払い済み」のみ)を受信したい場合は、次のセクションを参照してください。
サブスクライブするイベントの選択
リスト内の任意のエンドポイントを展開し、「Subscribed Events」セクションを使用して以下を選択します。
- All Events (Default): 現在サポートされているすべてのイベントが送信され、今後Kanorioに追加されるイベントも自動的に含まれます。
- Specific Events: このエンドポイントに必要なイベントのみを選択し(少なくとも1つ選択する必要があります)、「Save Subscription」をクリックして変更を直ちに適用します。
現在、以下の本番イベントと1つのテストイベントをサポートしています(JSONフィールドの詳細はWebhookイベントと署名検証を参照してください)。
| イベント名 | 送信タイミング | イベントコード |
|---|---|---|
| 注文の支払い完了 | 購入者が支払いを完了し、注文が正式に作成されたとき(注文ごとに1回送信) | ec.order.paid |
| 配送ステータスの変更 | 配送状況が「配送済み」、「店舗到着」、「配達完了」、または「配送例外」になったとき | ec.shipment.statusChanged |
| フォームの送信 | 訪問者がオンラインフォームを送信し、スパムチェックを通過したとき(フォームの入力内容とすべての質問への回答を含む) | customers.form.submitted |
| 権限の付与/取り消し | 購入、無料請求、または手動調整により、受講者がコースやダウンロードパッケージへのアクセス権を獲得または喪失したとき | deliverables.entitlement.granted / revoked |
| ユニットの完了 | 受講者がコース内のユニットを完了したとき(受講者ごとにユニット単位で1回送信) | deliverables.progress.unit_completed |
| コースの完了 | 受講者がコースの修了条件を満たしたとき(受講者ごとにコース単位で1回送信) | deliverables.progress.completed |
| クイズの受験 | 受講者がクイズを送信したとき(スコアと合否ステータスを含む) | deliverables.quiz.attempted |
| 修了証の発行 | 受講者が修了証を受け取ったとき(修了証番号と発行日を含む。受講者ごとにコース単位で1回) | deliverables.certificate.issued |
| コレクションアイテムの変更 | コレクション内の単一アイテムが作成、下書きとして更新、公開、非公開、または削除されたとき | collections.item.created / updated / published / unpublished / deleted |
| コレクションの一括変更 | アイテムが一括保存、CSV/JSON経由でインポート、またはAPI経由でコレクションに書き込まれたとき(単一のイベントとして送信) | collections.items.bulk_changed |
| 翻訳の公開/削除 | 多言語サイト内の特定のコンテンツが個別に公開または削除されたとき(例:修正後の保存、API書き込み、ソース変更後の自動翻訳など。サイト全体の翻訳時には個別に送信されません) | content.translation.published / deleted |
| ロケールの公開/非公開/更新 | ロケールが公開(サイト全体の翻訳完了または手動公開)、削除、無効化されたとき、またはURLプレフィックス、自動翻訳の切り替え、順序、プライマリ言語が更新されたとき | localization.locale.published / unpublished / updated |
| サイト全体の翻訳完了/失敗 | 言語の追加や「不足分の再実行」によって開始されたサイト全体の翻訳が終了したとき(翻訳済み、スキップ済み、失敗したアイテムの数を含む) | localization.job.completed / failed |
| 送信ドメインの無効化 | カスタム送信ドメインのDNS検証が失敗したとき(ドメインごとに1日最大1回) | customers.sendingDomain.degraded |
| メッセージング枠のアラート | 現在の請求期間のメール送信枠を使い切ったとき、自動チャージがトリガーされたとき、自動チャージが上限に達したとき、またはチャージの支払いが失敗したとき | customers.messagingQuota.alert |
| ストレージ枠のアラート | ストレージがほぼ満杯、または満杯になったとき、自動チャージがトリガーされたとき、自動チャージが上限に達したとき、またはチャージの支払いが失敗したとき | site.storageQuota.alert |
| 年間更新の通知 | 年間プランの更新前で、年間アドオンや未払いの追加料金/プラットフォーム料金がある場合(合計請求額をプレビュー) | site.subscription.upcomingRenewal |
| アドオン価格変更の通知 | アドオンの価格が調整される前(少なくとも30日前) | site.subscription.addOnPriceChange |
| トラフィックのマイルストーン | サイトの累計ユニーク訪問者数が100または500を超えたとき | site.analytics.milestone |
| 連携の停止 | 連続した失敗により、システムがWebhookエンドポイントを自動的に停止したとき(他の正常なエンドポイントには通知されますが、停止されたエンドポイントには送信されません) | customers.teamDestination.disabled |
| アクセスリクエスト | チームメンバーがダッシュボードで権限不足に遭遇し、アクセスリクエストを送信したとき(リクエストごとに1回送信) | team.accessRequest.created |
| テストイベント | パネルで「テスト送信」がクリックされたとき | team.test |
Webhookとチーム通知メールの違い
- 独立した管理: Webhookが送信されるかどうかは、「Website Settings › Developer › Webhooks」内の各エンドポイントのサブスクリプション設定のみに依存します。"Automations › Settings"で、「Send Webhook」が「N endpoints subscribed」または「Not connected」と表示されているか確認できますが、実際の切り替えはWebhookページで行います。
- チームメールの代替ではありません: Webhookを追加しても、Webサイトのオーナーやチームメンバーに送信される標準の通知メール(新規注文、フォーム返信など)が停止することはありません。チームメールを無効にしてWebhookのみを使用する場合は、「Store Notifications」または「Form Confirmation Emails」に移動し、チームメール設定をオフにしてください。
- メールクォータへの影響なし: WebhookはHTTPS経由で外部URLに直接プッシュされるため、Webサイトの月間メール送信クォータを消費しません。
ログの確認、手動再試行、自動一時停止
最近の配信と「Retry」の確認
エンドポイントを展開すると、「Recent Deliveries」セクションに直近10件の通知が表示されます。これにはイベント名、ステータス(Sent、Failed、Processing)、HTTPステータスコード、タイムスタンプが含まれます。レコードをクリックすると、試行回数、所要時間、次回の再試行時間、失敗理由を確認できます。
- コンテンツの表示(7日間保持): 通知から7日以内であれば、「View Content」をクリックして送信された完全なJSONペイロードを確認できます。
- 手動再試行(7日間保持): 受信側が一時的にダウンしていた場合や、フロー設定を修正した直後の場合、「Retry」をクリックして7日以内であれば通知を再送信できます。手動再試行は同じ通知IDを使用するため(受信側での重複排除が容易になります)、手動再試行が失敗しても、バックグラウンドでの再試行はトリガーされず、自動一時停止の制限にもカウントされません。
自動再試行と失敗時の自動一時停止
受信側が正しく応答しない場合、システムは応答ステータスに基づいて処理を行います。
- 自動指数バックオフ(最大8回、約2.5日間):
受信側が8秒以内に応答しない、ネットワークエラーが発生した、またはHTTP
429(Too Many Requests)や5xx(Server Error)が返された場合、Kanorioはバックグラウンドで自動的に再試行します:1分 → 5分 → 30分 → 2時間 → 8時間 → 24時間 → 24時間。最初の送信を含めて合計8回試行します。 - 再試行不可のエラー(
3xxおよびその他の4xx): 受信側がリダイレクト(301、302など)や設定エラー(400、401、403、404など)を返した場合、システムは再試行せず、1回の配信失敗としてカウントします。 - 即時一時停止(
410 Gone): 受信側が410 Goneを返した場合、URLが明示的に無効化されていることを示し、システムは直ちにエンドポイントを一時停止します。 - 3回連続失敗後の自動一時停止:
エンドポイントが3回連続で通知に失敗した場合(例:8回の再試行をすべて使い切った、または3回連続で
404エラーが発生した)、システムはエンドポイントを「Consecutively Failed, Paused」とマークし、プッシュを停止します。また、「Manage Integrations」権限を持つメンバー(オーナー、管理者、およびこの権限を持つカスタムロール)にプラットフォーム通知とメールを送信します。 - 再有効化の方法: 受信側(またはZapier/Makeフロー)を修正したら、"Website Settings › Developer › Webhooks"に戻り、エンドポイントを展開して「Send Test」をクリックして応答を確認し、「Re-enable」をクリックしてプッシュを再開します(失敗回数はゼロにリセットされます)。
よくある失敗理由とトラブルシューティング
「Send Test」や「Recent Deliveries」で失敗メッセージが表示された場合は、以下の表を参照してください。
| ダッシュボードでの失敗理由 | 意味 | 推奨されるアクション |
|---|---|---|
| 受信側が8秒後にタイムアウトしました | 受信側がリクエストの処理に時間がかかりすぎました | エンジニアに依頼し、受信側を「リクエストを検証した後すぐに 200 OK を返し、時間のかかるタスク(データベースへの書き込みやメール送信など)はバックグラウンドで処理する」ように更新してください |
| 受信側がリダイレクトを返しましたが、Kanorioは追跡しません | URLが 301、302、307、または 308 を返しました | 末尾のスラッシュ / の不足や余分な付与、またはドメインの変更が一般的です。Webhook URLを最終的な https:// URLに直接更新してください |
| 受信側のSSL証明書が無効または期限切れです | URLのHTTPS証明書が正しくインストールされていないか、期限切れか、自己署名されています | サーバーのSSL/TLS証明書を更新してください(信頼できる公開認証局によって発行されている必要があります) |
| このURLのドメインが見つかりません | DNSがドメインを解決できません | Webhook URLのタイプミスを確認し、ドメインのDNS AレコードまたはCNAMEレコードが有効であることを確認してください |
| 受信側に接続できません | 受信サーバーがダウンしているか、ファイアウォールによってブロックされています | サーバーが稼働していること、およびファイアウォールが以下に記載されている2つの静的なKanorio送信元IPを許可していることを確認してください |
| 受信側がリクエストを拒否しました (HTTP 401 / 403) | 認証または署名の検証に失敗しました | カスタムサーバーを使用している場合は、署名キーがKanorioパネルのものと一致していること、および検証に生のボディ(raw body)が使用されていることを確認してください |
| 受信側はこのURLを見つけられませんでした (HTTP 404) | URLパスが存在しないか、Zapier/Makeのフローが有効になっていません | URLのタイプミスを確認してください。n8nのテストURLやMakeを使用している場合は、リスナーがアクティブであるか、インターフェース上でフローが正式に有効になっていることを確認してください |
| 受信側が一時的にリクエスト頻度を制限しました (HTTP 429) | 受信側(またはZapier/Makeの無料プラン)がレート制限に達しました | システムが自動的に再試行をスケジュールします。これが頻繁に発生する場合は、プランの制限を確認するか、レート制限を引き上げてください |
| 受信側でエラーが発生しました (HTTP 5xx) | 内部サーバーエラー(例:500、502、503) | サーバーのエラーログを確認して問題を修正し、Kanorioで「再試行」をクリックしてください |
受信側にファイアウォールがある場合(静的IPホワイトリスト)
すべてのKanorio Webhookリクエスト(初期プッシュ、テスト送信、手動再試行、バックグラウンド再試行を含む)は、以下の2つのIPv4アドレスからローテーションで送信されます。サーバーやファイアウォールでIPホワイトリストを使用している場合は、両方のIPを許可してください。
| 静的送信元IP (IPv4) |
|---|
137.184.250.60 |
167.99.28.231 |
セキュリティ上の注意: IPホワイトリストはネットワーク層の追加防御であり、署名検証の代わりにはなりません。カスタム受信側では必ず
X-Kanorio-Signatureを検証してください。将来的に送信元IPを追加または変更する必要がある場合は、このページで事前にお知らせし、新旧IPの並行期間を設けます。
エンジニアへの引き継ぎ(署名キーとWebサイトID)
社内または外部のエンジニアと協力して受信プログラムを開発する場合は、ダッシュボードから以下の2つの情報と、Webhookイベントと署名検証の技術ドキュメントへのリンクを提供するだけで十分です。
- エンドポイントの「Signature Key (
whsec_...)」: "Website Settings › Developer › Webhooks"でエンドポイントを展開し、Signature Keyセクションの「Show」をクリックしてコピーします。- キーの漏洩が疑われる場合や定期的な更新が必要な場合: 「Generate New Key」をクリックします。更新後、古いキーは24時間有効なままです(その間、リクエストには両方のキーで計算された署名が含まれます)。これにより、エンジニアはダウンタイムなしでサーバー設定を更新できます。その24時間以内に再度「Generate New Key」をクリックすると、前のキーは直ちに無効になります。
- WebサイトID (
websiteId): サーバーが複数のKanorio WebサイトのWebhookを受信する場合、JSON内のwebsiteIdフィールドを使用してそれらを区別できます。websiteIdは"Website Settings › General"ページの一番下でコピーできます。
過去7日間のURL、署名キー、配信コンテンツは、Google Cloudのエンベロープ暗号化を使用して保存時に暗号化されます。ダッシュボードでキーが表示されたりコンテンツが閲覧されたりするたびに、監査ログが生成されます(キーと認証情報の保存方法を参照)。
よくある質問
いいえ。Webhookは無料プラン、プロプラン、ビジネスプランでサポートされており、最大10個のエンドポイントと詳細なイベントフィルタリングを利用できます。プランの変更やキャンセルによって、設定済みのURL、表示名、イベントサブスクリプション、署名キーが影響を受けることはありません。
受信側が応答に8秒以上かかった場合、ネットワークの一時的な不具合が発生した場合、またはダッシュボードで誰かが「Retry」をクリックした場合、同じ通知が再度送信されることがあります。再試行や手動再試行には、まったく同じ通知ID(ヘッダーX-Kanorio-DeliveryおよびJSON id)が含まれます。エンジニアや自動化フローでこのIDを使用して、重複を確認するようにしてください。
Kanorioは現在、標準的なJSON形式の汎用Webhookをプッシュします。Slack、Discord、Telegram、Microsoft Teams、またはGoogleスプレッドシートにデータを転送するには、まずWebhookをZapier、Make、またはn8nに接続し、それらのツールでデータを整形してチームのコミュニケーションツールに転送することをお勧めします。
Webhookイベントと署名検証で各イベントの完全なJSON例を参照するか、Webhookエンドポイントを作成して「Send Test」をクリックしてください。または、サイトで実際のイベント(テストフォームの送信など)が発生した後に、ダッシュボードの「Recent Deliveries」の下にある「View Content」をクリックして、実際のJSONペイロードを確認できます。