Verifikasi webhook Instagram: hub.challenge dan X-Hub-Signature-256
Menyiapkan webhook Instagram membutuhkan endpoint HTTPS yang menjawab GET verifikasi dari Meta, yang membawa hub.mode bernilai subscribe, hub.verify_token dan hub.challenge, dengan memeriksa token lalu mengembalikan challenge. Meta kemudian mengirim event JSON dalam POST yang ditandatangani di X-Hub-Signature-256 dengan secret aplikasi, setelah aplikasi berlangganan field dan setiap akun berlangganan melalui edge subscribed_apps-nya.
easyCoexistence menangani sisi Meta: aplikasinya lolos verifikasi, memeriksa X-Hub-Signature-256, berlangganan setiap akun Instagram yang terhubung ke comments, messages dan mentions, dan meneruskan event ke endpoint HTTPS Anda yang ditandatangani dengan X-EC-Signature dan secret per akun, sambil memantau setiap koneksi sepanjang waktu.
Nilai hub.mode selalu ada pada permintaan verifikasi Meta.
Jangka waktu selama Meta mencoba ulang notifikasi yang gagal, dengan frekuensi yang makin jarang, sebelum membuangnya.
Jumlah pengiriman pesan yang gagal sebelum Meta mengirim peringatan ke akun developer.
Jumlah pengiriman pesan yang gagal sebelum peringatan Webhooks Disabled dan pemutusan langganan aplikasi dari akun.
Mode aplikasi yang disyaratkan Meta sebelum aplikasi menerima notifikasi untuk akun penggunanya.
Bagaimana cara menyiapkan webhook Instagram?
Dalam empat langkah, sesuai urutan panduan Meta. Endpoint harus lolos verifikasi sebelum field apa pun dapat dipilih, aplikasi harus berstatus Live untuk menerima notifikasi untuk akun pengguna, dan verifikasi bisnis diperlukan untuk akses produksi.
Apa isi permintaan verifikasi?
GET ke URL callback, dikirim setiap kali produk Webhooks dikonfigurasi di App Dashboard. Jika hub.verify_token cocok dengan token milik endpoint, jawabannya adalah 200 dengan nilai hub.challenge sebagai seluruh body; jika tidak, 403. Dashboard melaporkan apakah endpoint lolos.
- hub.mode: selalu subscribe.
- hub.challenge: integer yang dibuat Meta, yang harus dikirim kembali oleh endpoint.
- hub.
verify_token: string yang dimasukkan di kolom Verify Token pada dashboard, yang hanya boleh diketahui Meta dan endpoint. - Di PHP, titik pada nama-nama ini menjadi garis bawah, sehingga nilainya tiba sebagai
hub_mode,hub_challengedanhub_verify_token.
GET https://<YOUR_HOST>/webhooks/instagram
?hub.mode=subscribe
&hub.challenge=1158201444
&hub.verify_token=<YOUR_VERIFY_TOKEN>
HTTP/1.1 200 OK
Content-Type: text/plain
1158201444Di mana callback dan field diatur?
Di App Dashboard, pada Instagram, API setup with Instagram login, Configure webhooks: URL callback dan verify token dimasukkan di sana, dan menyimpannya memicu permintaan verifikasi. Produk Instagram mulai berlangganan ke comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral dan messaging_seen, dan Manage dapat membatalkan langganan dari salah satunya. Tombol Test mengirim contoh notifikasi untuk field yang dipilih.
Bagaimana X-Hub-Signature-256 diperiksa?
Meta menandatangani setiap notifikasi event dengan HMAC-SHA256 dari payload, dengan kunci secret aplikasi, dan mengirimkannya di X-Hub-Signature-256 sebagai sha256= diikuti digest hex. Penerima menghitung HMAC yang sama atas raw body permintaan dan membandingkannya dengan header, dalam waktu konstan. Panduan pesan Meta mencatat bahwa tanda tangan mencakup payload dengan Unicode yang di-escape, sehingga hashing JSON yang sudah didekode atau diserialisasi ulang menghasilkan hasil yang berbeda.
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (!ok) return res.sendStatus(403);
res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});
// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
const expected = Buffer.from(
"sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
);
const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401);
}
res.sendStatus(200); // answer first, work after
const body = JSON.parse(req.body.toString("utf8"));
// hand body.entry to a queue or background job
});
app.listen(3000);Mengapa hanya secret aplikasi yang bisa memeriksanya?
Karena tanda tangan adalah HMAC yang menggunakan kunci secret tersebut. Tanpa secret itu, tidak ada yang bisa menghitung nilai yang diharapkan, dan tidak ada yang memegang salinan payload yang bisa memalsukannya, sehingga pemeriksaan harus dilakukan di server yang menerima permintaan Meta untuk aplikasi itu. Meta meminta agar secret aplikasi, access token dan kredensial klien tidak masuk ke log atau permintaan dukungan. Sistem yang menerima event yang diteruskan oleh aplikasi lain tidak bisa memeriksa tanda tangan Meta sama sekali, dan bergantung pada tanda tangan milik aplikasi tersebut.
Mengapa setiap akun memerlukan langganannya sendiri?
Karena App Dashboard menentukan apa yang dapat diterima aplikasi, dan notifikasi untuk suatu akun baru mulai setelah akun itu juga berlangganan. Dengan Instagram Login, kirim POST /<IG_ID>/subscribed_apps ke graph.instagram.com dengan access token User Instagram milik akun dan subscribed_fields yang berisi field yang dipilih untuk aplikasi, dipisahkan dengan koma. Panggilan yang berhasil mengembalikan success bernilai true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Apa yang dilakukan Meta saat pengiriman gagal?
Meta mencoba ulang, lalu menyerah. Panduan Meta meminta 200 OK untuk setiap notifikasi dan memperingatkan bahwa pengelompokan pembaruan, hingga 1.000 pembaruan, tidak dijamin. Pembaruan yang gagal langsung dicoba ulang, lalu beberapa kali lagi dengan frekuensi yang makin jarang selama 36 jam, dan setelah itu dibuang, sehingga event yang sama bisa tiba dua kali. Event pesan mengikuti aturan pengiriman pesan Meta, yang bertindak lebih cepat:
- 200 OK diharapkan dalam 5 detik, dan pengiriman yang gagal mendapat beberapa percobaan ulang langsung, sehingga lakukan deduplikasi berdasarkan mid pesan.
- Setelah 15 menit kegagalan, peringatan dikirim ke akun developer.
- Setelah satu jam kegagalan, peringatan Webhooks Disabled menyusul, dan aplikasi berhenti berlangganan dari webhook akun hingga ia berlangganan lagi.
- Pesan yang dikirim selama gangguan bisa tiba tidak berurutan, sehingga urutkan berdasarkan timestamp.
Apa yang perlu diperiksa saat tidak ada yang masuk?
Daftar periksa pemecahan masalah Meta, yang mencakup sebagian besar endpoint yang diam, dengan urutan ini:
- URL callback lolos pemeriksaan dan dapat dijangkau melalui HTTPS dengan sertifikat yang valid; sertifikat self-signed tidak didukung.
- Aplikasi memilih field dan memiliki tingkat akses yang dibutuhkannya, yaitu Advanced Access untuk comments dan
live_comments. - Notifikasi diaktifkan untuk akun melalui
subscribed_apps, dengan token dari pengaturan login yang sama. - Akun memenuhi aturan field: notifikasi komentar memerlukan media milik akun publik.
- Server mengembalikan success sebelum mulai mengerjakan pekerjaan yang lambat.
Mengapa easyCoexistence menandatangani ulang event yang diteruskan?
Karena tanda tangan Meta tidak bisa ikut diteruskan. Aplikasi easyCoexistence menerima pengiriman dari Meta, memeriksa X-Hub-Signature-256 dengan secret aplikasinya sendiri, langsung menjawab Meta, dan mengirim POST setiap entry untuk akun yang terhubung ke endpoint yang diatur untuk akun itu, di dalam body baru yang berisi platform, account_id, external_id dan entry. Header Meta tidak diteruskan dan tidak bisa diperiksa tanpa secret itu, sehingga setiap forward membawa Content-Type: application/json dan X-EC-Signature, yang dihitung dengan secret milik satu akun tersebut.
Bagaimana cara memverifikasi X-EC-Signature?
Header berbunyi t=<unix>,v1=<hex>, dengan v1 adalah HMAC-SHA256 hex dari timestamp, titik, dan raw body, dengan kunci signing secret akun. Hitung ulang atas byte persis seperti yang diterima, bandingkan dalam waktu konstan, dan tolak timestamp yang lebih dari 5 menit.
- Secret diawali whsec_ dan hanya ditampilkan sekali, oleh
set_social_webhook_destinationatau PUT /channels/:id/webhook saat URL diatur. - Mengatur URL lagi menerbitkan secret baru, dan URL bernilai null mematikan penerusan.
- Setiap event dikirim sekali, menunggu hingga 8 detik, tanpa mengikuti redirect, ke alamat HTTPS yang di-resolve ke IP publik.
- Menghapus koneksi membatalkan langganan akun dari webhook Meta dan menghapus endpoint serta secret-nya.
import hashlib, hmac, time
def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
"""Check X-EC-Signature on an event forwarded by easyCoexistence."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, malformed or older than 5 minutes
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), v1.encode())Kesalahan umum
- Mengembalikan challenge sebagai JSON atau dalam tanda kutip. Meta mengharapkan nilai hub.challenge itu sendiri sebagai body, dengan status 200.
- Melakukan hash pada body yang sudah di-parse. Parser body JSON membuang byte persis yang ditandatangani Meta, sehingga simpan raw body untuk HMAC dan parse setelahnya.
- Berlangganan aplikasi tetapi lupa akunnya. Sampai POST /<IG_ID>/subscribed_apps berhasil untuk suatu akun, tidak ada notifikasi yang masuk untuknya.
- Membiarkan endpoint gagal selama satu jam. Meta menonaktifkan webhook pesan dan membatalkan langganan aplikasi dari akun, yang lalu harus berlangganan lagi.
Aktifkan dengan set_social_webhook_destination atau Partner API. Mulai dari US$ 9 hingga US$ 0.75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Apa itu hub.challenge di webhook Instagram?
Integer yang dikirim Meta dalam GET verifikasinya. Setelah memeriksa hub.verify_token, endpoint mengembalikannya sebagai body respons, yang membuktikan bahwa endpoint menguasai URL tersebut.
Mengapa hub.mode dan hub.challenge hilang di PHP?
PHP mengubah titik pada nama parameter menjadi garis bawah, sehingga nilai verifikasi Meta tiba sebagai hub_mode, hub_challenge dan hub_verify_token.
Bagaimana mengaktifkan kembali webhook Instagram setelah Meta menonaktifkannya?
Perbaiki endpoint, lalu berlangganan ulang akun dengan POST /<IG_ID>/subscribed_apps dan field yang sama.
Apakah sertifikat self-signed berfungsi untuk endpoint webhook Instagram?
Tidak, Meta tidak mendukung sertifikat self-signed: URL callback harus dapat dijangkau melalui HTTPS dengan sertifikat yang valid, item pertama dalam daftar periksa pemecahan masalah Meta.
Lanjut membaca
Hubungkan saluran pertama Anda dalam dua menit.
Tanpa menunggu peninjauan platform. Hubungkan WhatsApp, Instagram, TikTok, atau saluran lainnya, lalu minta AI Anda untuk memposting, membalas, atau membuat laporan, dan lihat hasilnya langsung.
- Gratis 3 hari
- Batalkan kapan saja
- Hanya API resmi
- Dipantau 24/7
Diverifikasi pada