Autentikasi callback HTTP: parameter, aturan, dan catatan - ApsaraVideo VOD

Topik ini menjelaskan cara kerja callback HTTP untuk notifikasi event, termasuk prosedur dan proses autentikasinya.

Mekanisme callback HTTP

Anda men-deploy layanan HTTP untuk menerima pesan callback dan mengonfigurasi URL callback di ApsaraVideo VOD.
Ketika suatu event terjadi, server ApsaraVideo VOD mengirimkan permintaan HTTP POST ke URL callback tersebut. Notifikasi event dikirimkan dalam body HTTP.
Layanan HTTP Anda melakukan autentikasi signature pada permintaan HTTP POST tersebut. Jika autentikasi berhasil, layanan mengembalikan kode status HTTP 200 untuk menandakan callback berhasil. Jika kode status lain dikembalikan atau permintaan timeout, callback dianggap gagal. Untuk informasi lebih lanjut tentang proses autentikasi, lihat Proses autentikasi callback HTTP.
Jika callback berhasil, URL callback yang Anda konfigurasikan akan menerima notifikasi event tersebut. Jika callback gagal, ApsaraVideo VOD akan mencoba mengulang callback sebanyak dua kali. Jika ketiga percobaan tersebut gagal, ApsaraVideo VOD akan membuang notifikasi event tersebut. Untuk informasi lebih lanjut tentang validasi dan pengulangan callback, lihat Validasi dan pengulangan callback.

Cara menggunakan

Prasyarat

Layanan HTTP atau HTTPS telah dideploy untuk menerima pesan callback.
Akun Alibaba Cloud telah dibuat dan verifikasi identitas telah selesai. Untuk membuat Akun Alibaba Cloud, kunjungi website resmi Alibaba Cloud. Untuk informasi lebih lanjut, lihat Buat Akun Alibaba Cloud.
ApsaraVideo VOD telah diaktifkan. Untuk informasi lebih lanjut, lihat Aktifkan ApsaraVideo VOD.

Catatan penggunaan

ApsaraVideo VOD mendukung beberapa Wilayah layanan. Konfigurasi notifikasi event bersifat spesifik per Wilayah. Anda dapat mengonfigurasi metode callback dan alamat webhook yang berbeda untuk setiap Wilayah.
Callback HTTP mendukung beberapa alamat webhook untuk mendukung lingkungan pengembangan yang berbeda. Untuk informasi lebih lanjut, lihat Konfigurasi beberapa alamat webhook.

Prosedur

Konfigurasikan callback HTTP untuk notifikasi event di ApsaraVideo VOD.

Catatan

Callback yang dikonfigurasi di Konsol ApsaraVideo VOD merupakan konfigurasi global untuk layanan tersebut. Anda dapat menggunakan OpenAPI untuk mengonfigurasi callback global atau meng-override konfigurasi tersebut untuk satu permintaan tertentu.

Konfigurasi callback HTTP di Konsol

Login ke Konsol ApsaraVideo VOD.
Pada panel navigasi kiri, pilih Configuration Management > Media Processing > Callback.
Pada bilah navigasi atas, pilih Wilayah target dari daftar drop-down Wilayah di sebelah kanan Workbench.

Konfigurasikan Callback Settings. HTTP callback

Di samping Callback Settings, klik Modify.

Konfigurasikan parameter callback.

Parameter Name	Description
Callback Method	Pilih HTTP Request.
Callback URL	Tetapkan alamat webhook untuk menerima pesan callback. Ketika event callback terjadi, server ApsaraVideo VOD akan mengirimkan permintaan HTTP POST ke alamat ini. URL dapat memiliki panjang maksimal 256 byte. Multiple URL tidak didukung.
Callback Events	Pilih jenis event yang ingin Anda terima notifikasinya sesuai kebutuhan. Untuk informasi lebih lanjut tentang jenis event yang didukung oleh ApsaraVideo VOD dan detail setiap notifikasi event, lihat Daftar event. Catatan Jika Anda memilih AI Processing Completed, notifikasi akan dipicu untuk semua event AI, seperti AIMediaAuditComplete, AIMediaDNAComplete, dan AIVideoTagComplete.

Klik OK.

Opsional: Konfigurasikan Callback Authentication.
Jika metode callback adalah HTTP Request, Anda dapat menambahkan parameter autentikasi ke header permintaan HTTP atau HTTPS. Hal ini memungkinkan server penerima melakukan autentikasi signature untuk mencegah permintaan ilegal atau tidak valid.
1. Pada bagian Callback Authentication, klik Modify.
2. Tetapkan kunci autentikasi.
  Kunci autentikasi ini adalah bidang AuthKey dalam algoritma signature. Untuk informasi lebih lanjut, lihat Algoritma signature. Kunci ini dapat memiliki panjang maksimal 32 karakter dan harus berisi angka, huruf kapital, serta huruf kecil.
3. Klik OK untuk menyelesaikan konfigurasi.
4. Setelah Anda mengaktifkan autentikasi callback, konfigurasikan logika autentikasi yang sesuai pada server HTTP atau HTTPS penerima Anda. Untuk informasi lebih lanjut, lihat Proses autentikasi callback HTTP.

Konfigurasi callback HTTP menggunakan OpenAPI

Anda dapat memanggil operasi yang berbeda untuk mengonfigurasi callback global atau meng-override konfigurasi untuk satu permintaan tertentu.

Konfigurasi global: Panggil operasi Set Event Notification Configuration dengan menyetel parameter permintaan CallbackType ke HTTP, serta mengonfigurasi parameter lain seperti CallbackURL dan EventTypeList.
Override per permintaan: Anda dapat menetapkan alamat webhook untuk satu permintaan tertentu dengan menentukan bidang MessageCallback dalam parameter permintaan UserData. Fitur ini tersedia saat Anda memanggil operasi berikut untuk mengunggah file media atau mengirimkan pekerjaan pemrosesan media:

Catatan

Saat Anda menggunakan bidang UserData dalam MessageCallback untuk mengonfigurasi callback, Anda harus terlebih dahulu mengaktifkan notifikasi event global untuk ApsaraVideo VOD dan mengonfigurasi jenis event callback yang sesuai agar konfigurasi callback tersebut berlaku.

Picu event callback.
Setelah Anda mengonfigurasi notifikasi event, lakukan operasi di ApsaraVideo VOD, seperti mengunggah aset media (audio, video, atau gambar) atau mengirimkan pekerjaan pemrosesan media (transcoding atau snapshot), untuk memicu event callback.
Terima event callback.
Setelah event callback dipicu, jika callback berhasil, Anda dapat melihat notifikasi event tersebut di layanan penerima callback yang telah Anda deploy.

Prinsip autentikasi callback HTTP

Ketika metode callback adalah HTTP Request, Anda dapat menambahkan parameter autentikasi ke header HTTP (termasuk HTTPS). Hal ini memungkinkan server penerima melakukan autentikasi signature untuk mencegah permintaan ilegal atau tidak valid.

Catatan penggunaan

Mengaktifkan autentikasi callback HTTP bersifat opsional tetapi direkomendasikan. Jika Anda menetapkan kunci autentikasi (AuthKey), callback akan menyertakan semua informasi yang diperlukan oleh server penerima untuk melakukan autentikasi. Menetapkan AuthKey tidak memengaruhi fitur yang sudah ada, dan Anda dapat memutuskan apakah akan melakukan validasi di server Anda.
Jika Anda tidak menetapkan AuthKey, fitur callback HTTP tidak terpengaruh.

Parameter autentikasi

Parameter autentikasi berikut ditambahkan ke header callback HTTP:

Field	Description
X-VOD-TIMESTAMP	Bilangan bulat positif 10 digit yang menunjukkan Stempel waktu UNIX. Stempel waktu ini merepresentasikan jumlah detik yang telah berlalu sejak 1 Januari 1970 dan menunjukkan kapan permintaan callback dimulai.
X-VOD-SIGNATURE	String signature, yaitu hash MD5 32-bit. Untuk informasi lebih lanjut, lihat bagian Algoritma signature di bawah ini.

Algoritma signature

Nilai X-VOD-SIGNATURE dihitung berdasarkan field-field berikut:

Field	Example	Description
Callback URL	https://www.example.com/your/callback	URL callback yang Anda tetapkan.
X-VOD-TIMESTAMP	1519375990	Bilangan bulat positif 10 digit yang menunjukkan Stempel waktu UNIX. Stempel waktu ini merepresentasikan jumlah detik yang telah berlalu sejak 1 Januari 1970 dan menunjukkan kapan permintaan callback dimulai.
AuthKey	Test123	Kunci autentikasi yang ditentukan pengguna. Kunci ini dapat memiliki panjang maksimal 32 karakter dan harus berisi huruf kapital, huruf kecil, serta angka.

Gabungkan ketiga field tersebut dengan tanda VERTICAL LINE (|), lalu hitung hash MD5-nya:

MD5Content = Callback URL|X-VOD-TIMESTAMP|AuthKey
X-VOD-SIGNATURE = md5sum(MD5Content)

Contoh berikut menunjukkan cara menghitung field X-VOD-SIGNATURE:

X-VOD-SIGNATURE = md5sum(https://www.example.com/your/callback|1519375990|Test123) = c72b60894140fa98920f1279219b****

Aturan validasi untuk server penerima callback

Server penerima callback menggabungkan URL callback yang dikonfigurasi, nilai X-VOD-TIMESTAMP, dan AuthKey. Kemudian, server menghitung hash MD5 dari string gabungan tersebut dan membandingkan hasilnya dengan nilai field X-VOD-SIGNATURE. Jika nilainya tidak cocok, permintaan tersebut tidak valid.
Server penerima callback mengambil waktu saat ini dan membandingkannya dengan waktu yang ditentukan oleh field X-VOD-TIMESTAMP dalam permintaan callback. Jika selisihnya melebihi periode tertentu, misalnya 5 menit, permintaan tersebut dianggap tidak valid. Periode ini ditentukan oleh server penerima callback.
Catatan
Selisih waktu mungkin tidak akurat karena masalah seperti pengaturan waktu. Anda dapat memutuskan apakah akan melakukan validasi ini di server penerima callback.

Pergantian AuthKey

Saat Anda mengganti AuthKey, server penerima callback harus mendukung transisi yang mulus dengan mendukung AuthKey lama dan baru secara bersamaan untuk memastikan fitur callback tidak terganggu. Artinya, untuk periode tertentu, server harus mendukung autentikasi dengan kedua AuthKey tersebut. Server penerima callback bertanggung jawab menangani transisi ini.

Lakukan langkah-langkah berikut:

Tentukan AuthKey baru.
Perbarui server penerima callback agar mendukung autentikasi dengan AuthKey lama dan baru.
Perbarui AuthKey ke kunci baru di Konsol ApsaraVideo VOD.
Setelah periode Pengamatan, hapus dukungan untuk AuthKey lama dari server penerima callback.
Pergantian selesai.

Referensi

Untuk perbandingan antara callback HTTP dan callback MNS, lihat Perbandingan callback HTTP dan MNS.
Jika Anda mengalami masalah, lihat FAQ tentang notifikasi event.