Webhook¶

Webhook を利用することで、エンドユーザのアバターが変更されたタイミングで通知を受け取ることができます。これは、RESTful API を使ってアバター画像を取得する代わりに利用できます。

Webhook の流れ¶

Webhook のシーケンス図

Webhook を有効化する¶

コンソールからアプリの詳細画面へ遷移し、Webhook を有効化します。表示された秘密鍵を自社アプリが参照できる場所に保存します。アプリの変更画面から、通知受信用のエンドポイントURLを設定します。

ペイロード受信用エンドポイントを実装する¶

エンドユーザのアバターが更新されると、ペイロード受信用エンドポイントで通知を受信します。POSTリクエストのボディにペイロードが含まれています。

Info

ペイロード受信用エンドポイントへは、インターネット上からアクセスできる必要があります。IPアドレス等で制限された環境ではご利用になれません。

ペイロードの仕様¶

クエリパラメータ形式の以下のパラメータが含まれています。

パラメータ	内容
avatarId	着せ替えを行ったアバターID
event	イベント名。「avatar_updated」で固定
avatarImageUrl	アバター全身画像のURL。画像は240x320ピクセルサイズのアニメーションGIFです。
faceImageUrl	アバターバストアップ画像のURL。画像は120x120ピクセルサイズのGIFファイルです。
timestamp	UNIXタイムスタンプ。24時間以上前のタイムスタンプのリクエストは破棄してください。

ペイロードのサンプル¶

avatarId=5715702266724352&avatarImageUrl=https%3A%2F%2Fexample.com%2Favatar.gif&event=avatar_updated&faceImageUrl=https%3A%2F%2Fexample.com%2Fface.gif&timestamp=1603158368

認証¶

Avatar Play からのアクセスであることを認証するには、 X-Avatar-Signature ヘッダに設定される署名を検証します。

ペイロードと署名キーを使って、HMAC SHA256のアルゴリズムで署名を生成し、16進数表記に変換した文字列が、X-Avatar-Signature ヘッダの値と一致することを確認します。

Go

key, err := hex.DecodeString("{16進数表記の署名キー}"))
if err != nil {
    log.Fatal("failed to decode sign key")
    return err
}

mac := hmac.New(sha256.New, key)
if _, err := mac.Write(payload); err != nil {
    log.Fatal("failed to sign")
    return
}
sign := hex.EncodeToString(mac.Sum(nil))
// この値と、X-Avatar-Signature ヘッダの値を比較します。

C#

// 16進数表記の署名キーをバイト配列に戻す
var keyBytes = new List<byte>();
for (int i = 0; i < "{16進数表記の署名キー}".Length / 2; i++)
{
    keyBytes.Add(Convert.ToByte("{16進数表記の署名キー}".Substring(i*2, 2), 16));
}
var key = keyBytes.ToArray();

// 署名
var signBytes = new HMACSHA256(key).ComputeHash(System.Text.Encoding.UTF8.GetBytes(payload));
var sign = BitConverter.ToString(signBytes).ToLower().Replace("-", "");
// この値と、X-Avatar-Signature ヘッダの値を比較します。

アバター画像の更新¶

avatarImageUrl、faceImageUrl に設定されたURLからアバター画像をダウンロードし、自社アプリのストレージに保存してアバター画像として利用できるようにします。

ステータスコード¶

正常終了した場合、HTTPステータスコード 200 を返してください。200 が返ると、Webhook は接続に成功したと判断し、通知を終了します。それ以外のステータスコードが設定された場合、Webhook は処理に失敗したと判断します。

エンドポイントの処理時間¶

エンドポイントの処理時間は5秒以内完了を目標に実装してください。それ以上応答が返らなかった場合、Webhook はタイムアウト扱いにして処理に失敗したと判断します。

Webhook の動作¶

リトライ処理¶

ペイロード受信用エンドポイントへの接続に失敗したと判断した場合、Webhook は一定間隔をおいて接続をリトライします。数回試行しても接続に成功しない場合、リトライを中止し、そのイベントの通知を終了します。

通知のレイテンシ¶

通常、エンドユーザの着せ替え完了後直ちに通知が実行されますが、レイテンシが発生する可能性もあるため、その点を考慮する必要があります。

キャッシュについて¶

アバター画像URL¶

Webhook で取得したアバター画像URLのキャッシュは推奨しません。アバター画像URLは予告なく変更される可能性があるため、更新しないまま長期間利用する用途には向いていません。

アバター画像ファイル¶

Webhook ではアバター画像ファイル自体をキャッシュします。エンドユーザがアバターを変更した場合は Webhook 経由で検知し、更新します。

RESTful API を利用する場合との比較¶

RESTful API の Avatar API を使って画像取得する場合と比較します。

観点	Webhook	RESTful API
アバター画像の取得方法	Webhook 受信用のエンドポイントを用意し、通知受信時にアバター画像をダウンロードし、自社アプリのアバター画像を更新します。	アバターを表示する箇所で API を呼び出し、アバター画像を取得します。必要に応じてAPI 結果をキャッシュします。
レイテンシ	エンドユーザが着せ替えを完了してから通知を受信するまで遅延が発生します	通常は最新の情報を取得できます

Info

RESTful API のアクセス数が割り当てに到達する水準の場合、CDN によるキャッシュを適用させていただくことがあります。この場合、API のレスポンスが最新データより数秒遅延することがあります。

最終更新日: 2021-02-09