Webhook連携の設定

Adaptyのwebhook連携は、以下のステップで構成されています。

1. エンドポイントを設定する:
   1. サーバーが Content-Type ヘッダーを application/json に設定したAdaptyリクエストを処理できることを確認します。
   2. サーバーがAdaptyの検証リクエストを受信し、任意の 2xx ステータスとJSONボディで応答するよう設定します。
   3. 接続が確認されたら、サブスクリプションイベントを処理します。
2. Adapty ダッシュボードでwebhook連携を設定して有効化します。 Adaptyのイベントをカスタムイベント名にマッピングすることもできます。本番環境に切り替える前に、Sandbox環境でテストすることをおすすめします。
3. Adaptyがサーバーに検証リクエストを送信します。
4. サーバーが 2XX ステータスとJSONボディで応答します。
5. Adaptyが有効なレスポンスを受信すると、サブスクリプションイベントの送信を開始します。

Adaptyリクエストを処理するサーバーを設定する

AdaptyはWebhookエンドポイントに2種類のリクエストを送信します。

1. 検証リクエスト: 接続が正しく設定されているか確認するための初回リクエストです。このリクエストにはイベントは含まれず、Adapty ダッシュボードのWebhook連携で Save ボタンをクリックした瞬間に送信されます。エンドポイントが検証リクエストを正常に受信したことを確認するため、エンドポイントは検証レスポンスを返す必要があります。
2. サブスクリプションイベント: Adaptyサーバーでイベントが作成されるたびに送信される標準リクエストです。サーバーは特定のレスポンスを返す必要はありません。Adaptyサーバーが必要とするのは、メッセージを正常に受信した場合に標準の200コードHTTPレスポンスを受け取ることだけです。

検証リクエスト

Adapty ダッシュボードでwebhook連携を有効にすると、Adaptyは空のJSONオブジェクト {} をボディとして含むPOST検証リクエストを送信します。

エンドポイントの Content-Typeヘッダー が application/json になるよう設定してください。つまり、サーバーのエンドポイントは受信するWebhookリクエストのペイロードがJSON形式でフォーマットされることを想定している必要があります。

サーバーは2xxステータスコードで応答し、以下のような有効なJSONレスポンスを返す必要があります。

{}

Adaptyが正しい形式かつ2xxステータスコードの検証レスポンスを受信すると、AdaptyのWebhook連携は完全に設定された状態になります。

サブスクリプションイベント

サブスクリプションイベントは Content-Type ヘッダーが application/json に設定された状態で送信され、JSON形式のイベントデータが含まれます。可能なイベントタイプとリクエスト構造については、Webhookイベントの種類とフィールドを参照してください。

Adapty ダッシュボードでWebhook連携を設定する

Adaptyでは、本番イベントとApple・Sandbox環境またはGoogleテストアカウントから受信するテストイベントに対して、別々のフローを設定できます。

本番イベントには、コールバックの送信先URLを指定する Production endpoint URL フィールドを使用します。また、Authorization header value for production endpoint フィールドも設定してください。これはサーバーがAdaptyイベントを認証するためのヘッダーです。Authorization header value for production endpoint フィールドに指定した値は、変更や追加なしにそのまま Authorization ヘッダーとして使用されることにご注意ください。

テストイベントには、Sandbox endpoint URL と Authorization header value for sandbox endpoint フィールドをそれぞれ使用します。

Webhook連携を設定するには:

1. Adapty ダッシュボードで Integrations -> Webhook を開きます。

2. トグルをオンにして連携を開始します。

3. 連携フィールドに入力します。

   フィールド	説明
   Production endpoint URL	AdaptyがHTTP POSTリクエストを本番環境のイベントとして送信するURL。
   Authorization header value for production endpoint	本番環境でサーバーがAdaptyからのリクエストを認証するためのヘッダー。このフィールドに指定した値は、変更や追加なしにそのまま Authorization ヘッダーとして使用されることにご注意ください。 必須ではありませんが、セキュリティ強化のために強くお勧めします。

   サンドボックス環境でのテスト用に、さらに2つのフィールドが利用可能です。

   テストフィールド	説明
   Sandbox endpoint URL	AdaptyがサンドボックスHTTP POSTリクエストを送信するURL。
   Authorization header value for sandbox endpoint	サンドボックス環境でのテスト中にサーバーがAdaptyからのリクエストを認証するためのヘッダー。このフィールドに指定した値は、変更や追加なしにそのまま Authorization ヘッダーとして使用されることにご注意ください。 必須ではありませんが、セキュリティ強化のために強くお勧めします。

4. （任意）受信するイベントを選択して名前をマッピングします。様々な状況でどのイベントが発生するかは、イベントフローをご確認ください。

   イベントIDがAdaptyで使用されているものと異なる場合は、システム内のIDをそのまま維持し、Integrations -> Webhooks ページの Events names セクションでデフォルトのAdaptyイベントIDをご自身のIDに置き換えてください。

   イベントIDには任意の文字列を使用できます。Webhookを処理するサーバーのイベントIDと、Adapty ダッシュボードに入力したIDが一致していることを確認してください。有効なイベントのイベントIDを空のままにすることはできません。

5. その他のフィールドや設定は任意です。必要に応じて使用してください。

   設定	説明
   Send Trial Price	有効にすると、Adaptyは Trial Started イベントの price_local と price_usd フィールドにサブスクリプション価格を含めます。
   Exclude Historical Events	ユーザーがAdapty SDKを含むアプリをインストールする前に発生したイベントを除外するオプションです。これによりイベントの重複を防ぎ、正確なレポートを確保します。例えば、ユーザーが1月10日に月次サブスクリプションを有効化し、3月6日にAdapty SDK付きのアプリにアップデートした場合、Adaptyは3月6日より前のイベントを省略し、以降のイベントを保持します。
   Send user attributes	このオプションを有効にすると、言語設定などのユーザー固有の属性が送信されます。これらの属性は user_attributes フィールドに表示されます。詳細については、イベントフィールドを参照してください。
   Send attribution	このオプションをオンにすると、attributions フィールドにアトリビューション情報（AppsFlierデータなど）が含まれます。詳細はアトリビューションデータセクションを参照してください。
   Send Play Store purchase token	このオプションをオンにすると、必要に応じて購入の再検証に必要なPlay Storeトークンを受け取れます。有効にすると、イベントに play_store_purchase_token パラメータが追加されます。その内容の詳細については、Play Store購入トークンセクションを参照してください。

6. Save ボタンをクリックして変更を確定することを忘れないでください。

Save ボタンをクリックした瞬間、Adaptyは検証リクエストを送信し、サーバーからの検証レスポンスを待ちます。

送信するイベントを選択してイベント名をマッピングする

受信したいイベントの横にあるトグルを有効にして、サーバーで受信するイベントを選択します。Adaptyで使用されているイベント名と異なる名前を使用していて、そのままの名前を維持したい場合は、Integrations -> Webhooks ページの Events names セクションでデフォルトのAdaptyイベント名をご自身のものに置き換えてマッピングを設定できます。

イベント名には任意の文字列を使用できます。有効なイベントのフィールドを空のままにすることはできません。誤ってAdaptyのイベント名を削除してしまった場合は、サードパーティ連携に送信するイベントのトピックからいつでも名前をコピーできます。

Webhookイベントの処理

Webhookは通常、イベントが発生してから5〜60秒以内に配信されます。ただし、キャンセルイベントについては、ユーザーがサブスクリプションをキャンセルしてから配信されるまでに最大2時間かかる場合があります。

AdaptyのWebhook配信は「少なくとも1回」方式です。すべてのイベントは必ず1回以上配信され、失敗した場合は破棄せずにリトライします。サーバーのレスポンスステータスコードが200〜404の範囲外の場合、Adaptyは指数バックオフでリトライします。最初のリトライは初回失敗から約1分後に行われ、以降は試行ごとに間隔が2倍になります。最大9回リトライし、24時間にわたって分散されます。レスポンスを返す前に、Adaptyからのイベントボディの基本的なバリデーションだけを行うようWebhookを設定することをおすすめします。サーバーがイベントを処理できず、Adaptyにリトライさせたくない場合は、200〜404の範囲内のステータスコードを使用してください。また、時間のかかる処理は非同期で行い、Adaptyには素早くレスポンスを返してください。Adaptyが10秒以内にレスポンスを受け取れない場合、そのリトライは失敗とみなされ、再度リトライが行われます。

イベントは順序通りに届くとは限りません。順序付けと重複排除の方法については、イベントフィールドを参照してください。

繰り返しの失敗後に配信が一時停止された

エンドポイントへの直近の配信がほとんど失敗している場合、Adapty はアプリへの Webhook 配信を一時停止します。ここでの失敗の定義はリトライの場合と同じです。つまり、200〜404 の範囲外のレスポンスステータス、接続エラー、または 10 秒以内に応答がない場合です。配信が一時停止されている間、Adapty は新しいイベントをエンドポイントに送信せず、後でリトライすることもありません。これらのイベントは、サーバーがリクエストを受け取っていない場合でも、Sending failed ステータスとして表示されます。クールダウン後、Adapty はエンドポイントをテストするために次のイベントを送信します。その配信が成功すれば、通常の配信が再開されます。失敗した場合は、より長いクールダウンを経て再び配信が一時停止されます。

Save をクリックしたときに Adapty が送信する検証リクエストは、この配信パイプラインを経由しないため、配信が一時停止されていても成功する場合があります。

配信を継続するには、サーバーがまだユーザーと紐付けられないイベントも含め、すべてのイベントに対して 2xx ステータスを返し、自分側で処理してください。