利用を開始する

このドキュメントでは、アプリの利用者がユーザー写真の変更を公開したときに通知を受け取るWebhookを設定する方法について説明します。このWebhookの設定の仕方を理解すれば、すべてのWebhooksを設定できるようになるでしょう。

Webhookを設定するには、次のことを行う必要があります。

1. HTTPSリクエストを処理できるセキュアサーバーにエンドポイントを作成する。
2. アプリのアプリダッシュボードでWebhooks製品を構成する。

これらのステップは、以下で詳しく説明します。

エンドポイントを作成する

エンドポイントでは、確認リクエストとイベントのお知らせの2つのタイプのHTTPSリクエストを処理できることが必要です。両方のリクエストがHTTPSを使用するので、有効なTLSまたはSSL証明書がサーバーに適切に構成されインストールされている必要があります。自己署名証明書はサポートされていません。

以下のセクションでは、各タイプのリクエストに含まれる内容と、それらのリクエストへの応答の仕方について説明します。また、これらのリクエストを処理するようにあらかじめ構成されているサンプルアプリを使うこともできます。

確認リクエスト

アプリダッシュボードでWebhooks製品を構成すると、必ずエンドポイントURLにGETリクエストが送られます。確認リクエストには次のクエリ文字列パラメーターがエンドポイントURLの末尾に付け加えられる形で含まれます。このようになります。

確認リクエストの例

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock

注:PHPは、パラメーター名のピリオド(.)をアンダースコア(_)に変換します。

確認リクエストの検証

エンドポイントは確認リクエストを受け取ると、必ず次のことを行います。

• hub.verify_tokenの値が、あなたがアプリダッシュボードでWebhooks製品を構成した(このトークン文字列はまだ設定していない)ときに設定したトークンの確認フィールドの文字列と一致していることを確認する。
• hub.challenge値を返す。

あなたがアプリダッシュボードを開いてWebhooks製品を構成している場合(つまり、確認リクエストをトリガーしている場合)、ダッシュボードはエンドポイントがリクエストを正しく確認できたかどうかを示します。グラフAPIの/app/エンドポイントを使ってWebhooks製品を構成している場合は、APIは応答で成否を示します。

イベントのお知らせ

Webhooks製品を構成する際、あるobjectタイプの特定のfieldsをフォローします(例: userオブジェクトのphotosフィールド)。これらのフィールドのいずれかに変更が発生すると、その変更について説明するJSONペイロードを含んだPOSTリクエストがエンドポイントに送られます。

例えば、userオブジェクトのphotosフィールドをフォローしている場合、アプリユーザーの1人が写真を投稿すると、次のようなPOSTリクエストが送られてきます。

POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" } 

ペイロードのコンテンツ

ペイロードには、変更について説明するオブジェクトが含まれます。Webhooks製品の構成をしているとき、ペイロードに変更されたフィールドの名前だけを含めるのか、それとも新規の値も含めるのかを示せます。

ペイロードはすべてJSONでフォーマットされているので、一般的なJSON解析方法やパッケージを使ってペイロードを解析することができます。

ほとんどのペイロードには、以下の共通プロパティが含まれます。しかし、フォローしているオブジェクトフィールドによって、各ペイロードのコンテンツや構造は異なります。どのフィールドが含まれるかを確認するには、各オブジェクトのリファレンスドキュメントを参照してください。

ペイロードの確認

すべてのイベントのお知らせペイロードはSHA256で署名されます。この署名は、リクエストのX-Hub-Signature-256ヘッダーにあり、先頭にsha256=が付きます。ペイロードの確認は必須ではありませんが、推奨されています。

ペイロードを確認する手順は次のとおりです。

1. ペイロードとアプリのApp Secretを使って、SHA256署名を生成します。
2. 自分の署名とX-Hub-Signature-256ヘッダーにある署名(sha256=の後に続くものすべて)を比較します。署名が一致していれば、そのペイロードは本物です。

イベントのお知らせへの応答

エンドポイントはすべてのイベントのお知らせに200 OK HTTPSで応答するようにしてください。

頻度

イベントのお知らせは、最大1,000件のアップデートをまとめて1つのバッチで送信されます。しかし、バッチ処理は保証できないので、各Webhookを個別に処理するようにサーバーを調整してください。

サーバーに送信されたアップデートが失敗すると、Facebookがただちに再試行し、その後36時間、頻度を落としながら数回試行します。このような場合、サーバー側で重複排除の処理をする必要があります。36時間以内に認知されない応答はドロップされます。

注: Messengerイベントのお知らせごとに、送信頻度は異なります。詳しくは、MessengerプラットフォームWebhooksのドキュメントをご覧ください。

Webhooks製品を構成する

エンドポイントまたはサンプルアプリの用意ができたら、アプリのアプリダッシュボードを使ってWebhooks製品を追加し、構成します。プログラムを使用して同じ操作をすることもできます。その場合には、Instagram以外のすべてのWebhooksに対して/{app-id}/subscriptionsエンドポイントを使います。

この例では、ダッシュボードを使って、アプリの利用者の写真に加えられた変更をフォローするWebhookを構成します。

1. アプリダッシュボードの[製品] > [Webhooks]に移動し、ドロップダウンメニューから[ユーザー]を選択し、[このオブジェクトをフォローする]をクリックします。
   

   ユーザーオブジェクトを選択します。

2. [コールバックURL]フィールドにエンドポイントのURLを、[トークンの確認]フィールドに文字列を入力します。この文字列はすべての確認リクエストに含まれます。いずれかのサンプルアプリを使用している場合は、アプリのTOKEN構成変数に使った文字列と同じ文字列にしてください。

   イベントのお知らせペイロードに、変更されたフィールドの名前だけでなく新規の値も含める場合は、[値を含める]を[Yes]に切り替えます。
   

   エンドポイントURLと確認トークン文字列を入力します。

3. [確認して保存]をクリックすると、エンドポイントに確認リクエストが届くので、必ず確認してください。エンドポイントがリクエストの確認に成功すると、以下が表示されます。

   

   確認成功。

4. 最後のステップで、フィールドを個別にサブスクリプション登録します。photosフィールドをフォローし、テストイベント通知を送信します。

   

   ユーザーオブジェクトのPhotosフィールドをフォローします。

   エンドポイントが正しく設定されると、ペイロードが検証され、検証成功時に実行するよう設定されたコードが実行されます。サンプルアプリを使っている場合は、アプリのURLをウェブブラウザーで読み込んでください。ペイロードのコンテンツが次のように表示されます。

   

   テスト通知ペイロードを表示しているサンプルアプリ。

次のステップ

これでWebhooksの設定方法が理解できました。特定の製品のWebhooksの設定に関連するその他のステップについて補足するドキュメントを参照したい方は、以下をご覧ください。

• 広告アカウントのWebhooks
• 証明書の透明性のWebhooks
• InstagramのWebhooks
• リードのWebhooks
• MessengerのWebhooks
• Pages用のWebhooks
• 決済のWebhooks
• WhatsApp用のWebhooks