Webhook¶
Webhook は、Avatar Play 側で発生したイベントを、自社アプリのサーバサイド(以下、自社サーバ)に通知する仕組みです。
Webhook の流れ¶
次のシーケンス図は、着せ替え完了通知を例に、Webhook が自社サーバに通知するまでの流れを示しています。
Webhook を有効化する¶
コンソールからアプリの詳細画面へ遷移し、Webhook を有効化します。表示された秘密鍵を自社アプリが参照できる場所に保存します。アプリの変更画面から、通知受信用のエンドポイントURLを設定します。
ペイロード受信用エンドポイントを実装する¶
エンドユーザのアバターが更新されると、ペイロード受信用エンドポイントで通知を受信します。POSTリクエストのボディにペイロードが含まれています。詳細は各イベントのリファレンスを参照ください。
Info
ペイロード受信用エンドポイントへは、インターネット上からアクセスできる必要があります。IPアドレス等で制限された環境ではご利用になれません。
認証¶
Avatar Play からのアクセスであることを認証するには、 X-Avatar-Signature
ヘッダに設定される署名を検証します。
ペイロードと署名キーを使って、HMAC SHA256のアルゴリズムで署名を生成し、16進数表記に変換した文字列が、X-Avatar-Signature
ヘッダの値と一致することを確認します。
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 ヘッダの値を比較します。
// 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 ヘッダの値を比較します。
ステータスコード¶
正常終了した場合、HTTPステータスコード 200
を返してください。200
が返ると、Webhook は接続に成功したと判断し、通知を終了します。それ以外のステータスコードが設定された場合、Webhook は処理に失敗したと判断します。
エンドポイントの処理時間¶
エンドポイントの処理時間は5秒以内完了を目標に実装してください。それ以上応答が返らなかった場合、Webhook はタイムアウト扱いにして処理に失敗したと判断します。
古いリクエストを無視する¶
ペイロードには共通して、Webhook を通知した日時のUNIXタイムスタンプを保持する timestamp
パラメータが含まれます。不正なリクエスト(リプレイアタック)を処理しないよう、古い値を持つリクエストを無視するようにしてください。通常、10分以上古いタイムスタンプは無視して問題ありません。
Webhook の動作¶
リトライ処理¶
ペイロード受信用エンドポイントへの接続に失敗したと判断した場合、Webhook は一定間隔をおいて接続をリトライします。数回試行しても接続に成功しない場合、リトライを中止し、そのイベントの通知を終了します。
通知のレイテンシ¶
通常、イベント発生後直ちに通知が実行されますが、レイテンシが発生する可能性もあるため、その点を考慮する必要があります。