Webhook

自社開発またはAIツールで作ったウェブサイトを接続します。

設定時間の目安：7分

独自サイトやAIで構築したサイトにはWebhookを推奨します。サイト側の実装時間は設定時間に含まれません。

準備

サイトを作るAI開発ツール、または保守担当者。
ホスティング設定を変更できる権限。

サイトツールへ接続指示を渡す

現在のページとデザインを保ち、既存ブログへSurpassoを接続するよう、下の説明をサイトのAI開発ツールへコピーします。ブログがなければ追加するよう依頼します。

接続手順を表示

Surpasso は企業の SEO・GEO 記事の企画、執筆、公開を支援する製品です。既存サイトを Surpasso に接続してください。最初にフレームワーク、ブログのルート、記事の保存方法、デザイン、デプロイ方法を確認し、既存機能を優先して再利用します。サイトを作り直したり、既存記事を削除・上書きしたりしないでください。

Webhook を使用します。Surpasso が記事を送信し、サイトが保存して表示します。既存 CMS の書き込み処理を再利用し、公開 HTTPS POST 受信先（例：/api/surpasso-webhook）を追加してください。ブログがなければ、現行デザインに沿って必要な記事保存、一覧、詳細ページを追加します。まずデプロイ可能な受信 URL を返してください。SURPASSO_WEBHOOK_SECRET が設定されるまでは必ず要求を拒否し、検証を無効にしないでください。その後、Surpasso に URL を保存し、署名シークレットを取得し、デプロイ環境へ SURPASSO_WEBHOOK_SECRET を設定してからテストします。

JSON エンベロープ：{schemaVersion:"1",event,deliveryId,idempotencyKey,occurredAt,article}。ヘッダー：x-surpasso-timestamp、x-surpasso-signature（sha256=16進署名）、x-surpasso-event、x-surpasso-delivery。変更していない rawBody を使い、HMAC-SHA256(secret, timestamp + "." + rawBody) を計算し、定数時間比較と5分のタイムスタンプ範囲で検証します。不正な構造は拒否してください。integration.test は article:null です。検証後 2xx を返し、記事は作成しません。article.draft_created は非公開下書き、article.published は公開、article.updated は公開状態を維持して同じ記事を更新します。現在 unpublish/delete イベントはないため、自動削除対応をうたわないでください。

フィールド対応：id は安定した記事識別子、revision はコンテンツ版、title は見出し、slug は記事パス、excerpt は要約、contentMarkdown / contentHtml は本文（既存エディターに合う形式を選び、HTML は安全に処理）、metaTitle / metaDescription は SEO メタデータ、featuredImage.url / alt はカバー画像と代替テキスト、images は本文画像、author / authorType / authorUrl は著者、editor / reviewer と各 Type / Url は編集クレジット、categories / tags は分類、language はコンテンツ言語、contentFamilyId / alternates は多言語関係とリンク、structuredData は構造化データ、canonicalUrl は正規 URL です。最終 URL にはサイトの実際の公開パスを使い、誤った canonical をコピーしないでください。null は適切に処理し、未対応の任意フィールドで公開を止めないでください。

article.id とローカル記事の対応を Product/brandId 単位で永続化し、古い revision を拒否します。deliveryId / idempotencyKey は配信重複排除用に永続化し、配信キーを記事 ID として扱わないでください。処理済みの重複には成功を返しますが、記事を再作成しません。書き込み成功または永続キューへの受理後にのみ 2xx を返します。送信側は12秒でタイムアウトし、リダイレクトを拒否します。不正署名、古い時刻、接続テスト、下書き、公開、更新、重複配信、古い revision をテストしてください。

必要な確認を実行した後、変更した機能、デプロイ手順、設定する環境変数名と設定先、Surpasso に戻して入力する URL、記事の新規公開と更新を確認する方法を、一般ユーザーにも分かる言葉で説明してください。秘密情報はサイトのデプロイ環境の環境変数で設定するよう案内し、チャット、Git、ブラウザーコードには入れさせないでください。

変更を公開し、記事を受け取る本番URLを取得します。ホームページや例ではなく、サイトツールが作ったhttps://example.com/api/surpasso-webhookのようなURLを使います。

URLと接続キーを保存する

SurpassoのIntegrations → Custom → Webhookで受信URLがあるを選び、URLを保存します。
一度だけ表示される接続キーをコピーします。
サイトの環境変数へSURPASSO_WEBHOOK_SECRETとして保存し、再デプロイします。
Surpassoへ戻り完了を確認します。

テストと記事確認

接続をテストはテストメッセージだけを送り、記事を作りません。成功後Content Calendarから下書きを送り、サイト管理画面で本文と画像を確認して公開します。同じ記事を編集・再送し、重複せず元記事が更新されることを確認します。

削除・非公開化はサイトのブログ管理画面で行います。Webhookは外部記事を自動削除しません。Make、Zapier、n8nも利用できますが、本番受信URL、署名確認、ブログ保存、記事と編集の実地確認が必要です。

テスト失敗、記事欠落、重複

実装が公開済みで、URLがHTTPSかつログインやリダイレクトなしで動き、キー保存後に再デプロイしたか確認します。受信側は12秒以内に応答し、同じdeliveryを重複作成せず、revisionの古い更新で新しい記事を上書きしない必要があります。不明な結果の場合は再試行前にサイトを確認します。

キーを紛失・漏えいした

旧キーの利用を止め、SurpassoでWebhookを切断・再接続し、新キーを環境変数へ保存して再デプロイ・再テストします。完全な旧キーは再表示できません。

技術仕様：イベントと署名

JSON POSTにはschemaVersion: "1"、event、deliveryId、idempotencyKey、occurredAt、articleが入ります。integration.testは検証のみ、article.publishedは公開、article.updatedは同じ記事を状態保持で更新します。

ヘッダーのx-surpasso-timestampとraw bodyをtimestamp + "." + rawBodyとしてHMAC-SHA256計算し、x-surpasso-signatureのsha256=値と定数時間比較します。5分を超える時刻を拒否し、構造、重複、revisionも検証してください。署名確認だけでは完全な受信実装になりません。