Chrome Extension Kit

ARTICLE

Cloudflare WorkerでPolar.sh Webhookを受ける

WebhookイベントがCloudflare Workerへ届く流れを表す図。

有料Chrome拡張では、購入完了、返金、サブスクリプション更新、Benefit付与などのイベントを自分のシステムへ反映する必要があります。 この非同期通知に使うのがWebhookです。 Polar.shはWebhookを使って、購入や権利に関するイベントを指定したエンドポイントへ送信できます。

Chrome Extension Kit の構成では、このWebhook受信先としてCloudflare Workerを使うのが扱いやすいです。 LP、checkout作成API、Webhook受信、ライセンス検証APIをCloudflare上にまとめることで、小さな有料拡張でもサーバー構成を重くしすぎずに済みます。

Webhookで最初に実装すべきなのは、署名検証です。 Webhookはインターネット上のURLへPOSTされるため、受け取ったJSONをそのまま信用してはいけません。 Polar.shのWebhookはStandard Webhooks形式に沿っており、SDKの署名検証ヘルパーを使うか、仕様に沿って署名を検証します。 署名検証に失敗したリクエストは処理せず、ログに残して終了します。

次に、イベント種別ごとの処理を決めます。 購入完了イベントでは、注文ID、顧客ID、Product、Benefit、メールアドレスなどを保存します。 Benefit付与イベントでは、対象ユーザーにどの権利が付いたのかを記録します。 返金や解約に関係するイベントでは、ライセンスや権利を無効化する必要があります。

Webhook処理では、同じイベントが複数回届いても問題ない設計にします。 ネットワークや再送の都合で、Webhookは一度だけ届くとは限りません。 event id や order id を保存し、すでに処理済みなら二重に招待や付与をしないようにします。 これを冪等性と呼びます。

Chrome拡張側には、Polar.shのシークレットや管理用APIキーを置かないでください。 拡張はユーザーのブラウザに配布されるため、同梱した秘密情報は秘密ではありません。 checkout作成、Webhook受信、ライセンス検証のような秘密情報を使う処理は、Cloudflare Worker側に寄せます。

ローカル開発では、Webhookを直接受けるためにトンネルツールを使うことがあります。 ただし、本番ではCloudflare Workerの公開URLをPolar.shのWebhook endpointとして登録し、sandbox環境と本番環境のシークレットを分けてください。

Webhookは「購入されたら何かする」ためだけの仕組みではありません。 購入後の権利状態を正しく保つための同期ポイントです。 有料Chrome拡張では、Webhook、DB、ライセンス検証API、拡張内キャッシュが一貫するように設計すると、サポートしやすい課金基盤になります。

References