コンテンツにスキップ

Webhook

Webhook は、Avatar Play 側で発生したイベントを、自社アプリのサーバサイド(以下、自社サーバ)に通知する仕組みです。

Webhook の流れ

次のシーケンス図は、着せ替え完了通知を例に、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 は一定間隔をおいて接続をリトライします。数回試行しても接続に成功しない場合、リトライを中止し、そのイベントの通知を終了します。

通知のレイテンシ

通常、イベント発生後直ちに通知が実行されますが、レイテンシが発生する可能性もあるため、その点を考慮する必要があります。


最終更新日: 2023-03-07