Pengesahan webhook Instagram: hub.challenge dan X-Hub-Signature-256
Menyediakan webhook Instagram memerlukan endpoint HTTPS yang menjawab GET pengesahan Meta, yang membawa hub.mode bernilai subscribe, hub.verify_token dan hub.challenge, dengan menyemak token dan memulangkan challenge. Kemudian Meta menghantar POST peristiwa JSON yang ditandatangani dalam X-Hub-Signature-256 dengan rahsia aplikasi, apabila aplikasi melanggan medan dan setiap akaun dilanggan melalui hubungan subscribed_apps.
easyCoexistence menguruskan bahagian Meta: aplikasinya lulus pengesahan, menyemak X-Hub-Signature-256, melanggan setiap akaun Instagram yang disambungkan kepada komen, mesej dan sebutan, dan memajukan peristiwa ke endpoint HTTPS anda yang ditandatangani dengan X-EC-Signature dan rahsia bagi setiap akaun, sambil memantau setiap sambungan sepanjang masa.
Nilai hub.mode sentiasa dibawa dalam permintaan pengesahan Meta.
Tempoh Meta mencuba semula pemberitahuan yang gagal, dengan kekerapan yang semakin berkurang, sebelum membuangnya.
Bilangan penghantaran mesej yang gagal sebelum Meta menghantar amaran kepada akaun pembangun.
Bilangan penghantaran mesej yang gagal sebelum amaran Webhooks Disabled dan aplikasi dinyahlanggan daripada akaun.
Mod aplikasi yang diperlukan Meta sebelum aplikasi menerima pemberitahuan bagi akaun pengguna.
Bagaimana penyediaan webhook Instagram berfungsi?
Dalam empat langkah, mengikut urutan panduan Meta. Endpoint mesti lulus pengesahan sebelum sebarang medan boleh dipilih, aplikasi mesti berada dalam mod Live untuk menerima pemberitahuan bagi akaun pengguna, dan pengesahan perniagaan diperlukan untuk akses pengeluaran.
Apakah kandungan permintaan pengesahan?
GET ke URL panggil balik, dihantar setiap kali produk Webhooks dikonfigurasi dalam App Dashboard. Apabila hub.verify_token sepadan dengan token endpoint itu sendiri, jawapannya ialah 200 dengan nilai hub.challenge sebagai keseluruhan badan; jika tidak, 403. Dashboard melaporkan sama ada endpoint lulus.
- hub.mode: sentiasa subscribe.
- hub.challenge: integer yang dijana Meta, yang mesti dihantar semula oleh endpoint.
- hub.
verify_token: rentetan yang dimasukkan dalam medan Verify Token di dashboard, yang hanya Meta dan endpoint patut tahu. - Dalam PHP, titik dalam nama-nama ini menjadi garis bawah, jadi nilai 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 URL panggil balik dan medan ditetapkan?
Dalam App Dashboard, di bawah Instagram, API setup with Instagram login, Configure webhooks: URL panggil balik dan token pengesahan dimasukkan di sana, dan apabila disimpan ia mencetuskan permintaan pengesahan. Produk Instagram bermula dilanggan kepada comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral dan messaging_seen, dan Manage menyahlanggan mana-mana daripadanya. Butang Test menghantar pemberitahuan contoh bagi medan yang dipilih.
Bagaimana X-Hub-Signature-256 disemak?
Meta menandatangani setiap pemberitahuan peristiwa dengan HMAC-SHA256 bagi payload, dikunci dengan rahsia aplikasi, dan menghantarnya dalam X-Hub-Signature-256 sebagai sha256= diikuti digest heksadesimal. Penerima mengira HMAC yang sama ke atas badan permintaan mentah dan membandingkannya dengan header dalam masa malar. Panduan pemesejan Meta menyatakan bahawa tandatangan meliputi payload dengan Unicode di-escape, jadi menghasilkan semula JSON yang telah dinyahkod atau disusun semula akan memberi keputusan yang berbeza.
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 rahsia aplikasi boleh menyemaknya?
Kerana tandatangan ialah HMAC yang dikunci dengan rahsia itu. Tanpanya, tiada sesiapa boleh mengira nilai yang dijangka, dan sesiapa yang memegang salinan payload tidak boleh memalsukannya, jadi semakan itu mesti berada pada pelayan yang menerima permintaan Meta bagi aplikasi tersebut. Meta meminta rahsia aplikasi, access token dan kelayakan klien dikekalkan di luar log dan permintaan sokongan. Sistem yang menerima peristiwa yang dihantar oleh aplikasi lain tidak boleh menyemak tandatangan Meta sama sekali, dan bergantung pada tandatangan aplikasi itu sendiri.
Mengapa setiap akaun memerlukan langganan sendiri?
Kerana App Dashboard menetapkan apa yang boleh diterima aplikasi, dan pemberitahuan bagi sesuatu akaun hanya bermula apabila akaun itu juga dilanggan. Dengan Instagram Login, hantar POST /<IG_ID>/subscribed_apps ke graph.instagram.com dengan access token pengguna Instagram bagi akaun itu dan subscribed_fields yang menyenaraikan medan yang dipilih untuk aplikasi, dipisahkan dengan koma. Panggilan yang berjaya memulangkan success bernilai true.
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Apakah yang Meta lakukan apabila penghantaran gagal?
Ia mencuba semula, kemudian berhenti. Panduan Meta meminta 200 OK bagi setiap pemberitahuan dan memberi amaran bahawa pengelompokan, sehingga 1,000 kemas kini, tidak dijamin. Kemas kini yang gagal dicuba semula serta-merta, kemudian beberapa kali lagi dengan kekerapan yang semakin berkurang selama 36 jam, dan dibuang selepas itu, jadi peristiwa yang sama boleh tiba dua kali. Peristiwa pemesejan mengikut peraturan penghantaran pemesejan Meta, yang bertindak lebih pantas:
- 200 OK dijangka dalam masa 5 saat, dan penghantaran yang gagal mendapat beberapa cubaan semula segera, jadi buang pendua berdasarkan mid mesej.
- Selepas 15 minit kegagalan, amaran dihantar ke akaun pembangun.
- Selepas sejam kegagalan, amaran Webhooks Disabled menyusul, dan aplikasi dinyahlanggan daripada webhook akaun itu sehingga ia melanggan semula.
- Mesej yang dihantar semasa gangguan boleh tiba tidak mengikut urutan, jadi susun mengikut cap masa.
Apa yang perlu disemak apabila tiada apa yang tiba?
Senarai semak penyelesaian masalah Meta, yang meliputi kebanyakan endpoint senyap, mengikut urutan ini:
- URL panggil balik lulus semakannya dan boleh dicapai melalui HTTPS dengan sijil sah; sijil yang ditandatangani sendiri tidak disokong.
- Aplikasi memilih medan dan mempunyai tahap akses yang diperlukan, Advanced Access bagi comments dan
live_comments. - Pemberitahuan diaktifkan bagi akaun melalui
subscribed_apps, dengan token daripada persediaan log masuk yang sama. - Akaun memenuhi peraturan medan: pemberitahuan komen memerlukan media yang dimiliki oleh akaun awam.
- Pelayan memulangkan success sebelum memulakan kerja yang perlahan.
Mengapa easyCoexistence menandatangani semula peristiwa yang dimajukan?
Kerana tandatangan Meta tidak boleh dibawa bersama. Aplikasi easyCoexistence menerima penghantaran Meta, menyemak X-Hub-Signature-256 dengan rahsia aplikasinya sendiri, membalas Meta serta-merta, dan menghantar POST setiap entry bagi akaun yang disambungkan ke endpoint yang ditetapkan untuk akaun itu, dalam badan baharu yang mengandungi platform, account_id, external_id dan entry. Header Meta tidak dimajukan dan tidak dapat disemak tanpa rahsia itu, jadi setiap penghantaran membawa Content-Type: application/json dan X-EC-Signature, dikunci dengan rahsia yang milik akaun itu sahaja.
Bagaimana X-EC-Signature disahkan?
Header berbunyi t=<unix>,v1=<hex>, dengan v1 ialah HMAC-SHA256 heksadesimal bagi cap masa, titik, dan badan mentah, dikunci dengan rahsia tandatangan akaun. Kira semula ke atas bait tepat seperti yang diterima, bandingkan dalam masa malar, dan tolak cap masa yang lebih dari 5 minit lama.
- Rahsia bermula dengan whsec_ dan dipaparkan sekali sahaja, oleh
set_social_webhook_destinationatau PUT /channels/:id/webhook apabila URL ditetapkan. - Menetapkan URL semula akan mengeluarkan rahsia baharu, dan URL null mematikan pemajuan.
- Setiap peristiwa dihantar sekali, menunggu sehingga 8 saat, tanpa mengikut ubah hala, ke alamat HTTPS yang diselesaikan kepada IP awam.
- Membuang sambungan itu menyahlanggan akaun daripada webhook Meta dan mengosongkan endpoint dan rahsianya.
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())Kesilapan biasa
- Memulangkan challenge sebagai JSON atau dalam tanda petik. Meta menjangkakan nilai hub.challenge itu sendiri sebagai badan, dengan status 200.
- Mencincang badan yang telah dihurai. Pengurai badan JSON membuang bait tepat yang ditandatangani Meta, jadi simpan badan mentah untuk HMAC dan hurai selepas itu.
- Melanggan aplikasi tetapi terlupa akaun. Sehingga POST /<IG_ID>/subscribed_apps berjaya bagi sesuatu akaun, tiada pemberitahuan tiba untuknya.
- Membiarkan endpoint gagal selama sejam. Meta mematikan webhook pemesejan dan menyahlanggan aplikasi daripada akaun itu, yang kemudian perlu dilanggan semula.
Aktifkan dengan set_social_webhook_destination atau Partner API. Daripada US$ 9 hingga US$ 0.75 setiap sambungan sebulan, menurun apabila anda menambah sambungan, dengan 3 hari pertama percuma.
Soalan lazim
Apakah hub.challenge dalam webhook Instagram?
Integer yang dihantar Meta dalam GET pengesahannya. Selepas menyemak hub.verify_token, endpoint memulangkannya sebagai badan respons, yang membuktikan ia mengawal URL itu.
Mengapa hub.mode dan hub.challenge tiada dalam PHP?
PHP menukar titik dalam nama parameter kepada garis bawah, jadi nilai pengesahan Meta tiba sebagai hub_mode, hub_challenge dan hub_verify_token.
Bagaimana anda mengaktifkan semula webhook Instagram selepas Meta mematikannya?
Betulkan endpoint, kemudian langgan akaun itu semula dengan POST /<IG_ID>/subscribed_apps dan medan yang sama.
Adakah sijil yang ditandatangani sendiri berfungsi untuk endpoint webhook Instagram?
Tidak, Meta tidak menyokong sijil yang ditandatangani sendiri: URL panggil balik mesti boleh dicapai melalui HTTPS dengan sijil sah, item pertama dalam senarai semak penyelesaian masalah Meta.
Teruskan membaca
Sambungkan saluran pertama anda dalam masa dua minit.
Tidak perlu menunggu semakan platform. Sambungkan WhatsApp, Instagram, TikTok atau saluran lain, kemudian minta AI anda menyiarkan, membalas atau melaporkan, dan lihat ia bekerja.
- 3 hari percuma
- Batal bila-bila masa
- API rasmi sahaja
- Dipantau 24/7
Disahkan pada