Verifikasi webhook Facebook: hub.challenge dan X-Hub-Signature-256
Facebook memverifikasi endpoint webhook dengan GET yang membawa hub.mode bernilai subscribe, hub.verify_token dan hub.challenge; endpoint memeriksa token terhadap yang ada di App Dashboard lalu mengembalikan challenge sebagai body. Setiap event kemudian datang sebagai POST yang ditandatangani di X-Hub-Signature-256: sha256= diikuti HMAC-SHA256 dari payload, dengan kunci app secret.
easyCoexistence menangani sisi Meta untuk setiap Page yang Anda hubungkan: app-nya menjawab hub.challenge, memeriksa X-Hub-Signature-256 dan berlangganan Page untuk feed, pesan dan mention, lalu meneruskan event ke endpoint HTTPS Anda yang ditandatangani dengan X-EC-Signature dan secret khusus untuk Page tersebut.
Nilai yang selalu dibawa hub.mode dalam permintaan verifikasi Meta; hub.challenge adalah integer yang harus dikembalikan.
Awalan X-Hub-Signature-256, diikuti tanda tangan SHA256 yang dibuat Meta dari payload dan App Secret.
Seberapa cepat endpoint webhook Messenger harus membalas setiap notifikasi dengan 200 OK.
Jumlah pengiriman gagal sebelum alert Webhooks Disabled dan pembatalan langganan app dari Page.
Berapa lama Meta mencoba kembali notifikasi Page yang gagal, dengan frekuensi makin jarang, sebelum membuangnya.
Apa isi permintaan verifikasi Meta?
Sebuah GET ke callback URL, dikirim setiap kali produk Webhooks dikonfigurasi di App Dashboard atau langganan dibuat melalui /{app-id}/subscriptions. Tiga query parameter menyertainya:
- hub.mode: selalu subscribe.
- hub.challenge: integer yang harus dikirim kembali oleh endpoint.
- hub.
verify_token: string yang dimasukkan di kolom Verify Token pada dashboard. - PHP mengubah titik menjadi garis bawah, sehingga dibaca sebagai
hub_mode,hub_challengedanhub_verify_token.
Bagaimana endpoint harus menjawabnya?
Dengan 200 yang seluruh body-nya adalah nilai hub.challenge, tetapi hanya jika hub.mode bernilai subscribe dan hub.verify_token cocok; selain itu dibalas 403, seperti pada aplikasi contoh Meta. Dashboard melaporkan apakah endpoint lulus, dan /{app-id}/subscriptions menjawab dengan sukses atau kesalahan. Endpoint memerlukan HTTPS dengan sertifikat TLS atau SSL yang valid, karena sertifikat self-signed tidak didukung.
Bagaimana X-Hub-Signature-256 dihitung?
Sebagai HMAC-SHA256 dari payload permintaan dengan kunci App Secret aplikasi, ditulis dalam hex huruf kecil setelah sha256=. Panduan Messenger dari Meta menambahkan bahwa tanda tangan mencakup payload dengan Unicode di-escape, sehingga string seperti äöå dihitung sebagai \u00e4\u00f6\u00e5: hash body mentah persis seperti diterima, jangan salinan yang sudah di-decode atau diserialisasi ulang. Meta menyatakan validasi bersifat opsional tetapi sangat dianjurkan.
Bagaimana cara memeriksanya dalam kode?
Simpan byte mentah, hitung HMAC, bandingkan dengan waktu konstan, baru kemudian parse. get_data dari Flask mengembalikan body tanpa diubah, yaitu data yang dipakai untuk menghitung tanda tangan; mem-parse lalu menyerialisasi ulang akan mengubah byte-nya. Berikut endpoint kecil yang menjawab verifikasi dan memeriksa setiap POST:
import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
@app.get("/webhooks/facebook")
def verify():
token = request.args.get("hub.verify_token", "")
if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
return request.args.get("hub.challenge", ""), 200
abort(403)
@app.post("/webhooks/facebook")
def receive():
raw = request.get_data() # the bytes Meta signed
expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
abort(401)
# answer at once; hand request.get_json() to a queue for the work
return "EVENT_RECEIVED", 200Apa yang diharapkan Meta setelah verifikasi?
200 OK untuk setiap notifikasi, dalam 5 detik untuk event Messenger. Meta mengirim hingga 1,000 update per pengiriman tanpa jaminan, dan menangani kegagalan dengan cara berikut:
- Notifikasi Page: dicoba kembali segera, lalu beberapa kali lagi dengan frekuensi makin jarang selama 36 jam, kemudian dibuang.
- Notifikasi Messenger: dicoba kembali beberapa kali segera; setelah 15 menit kegagalan, alert dikirim ke akun developer.
- Setelah satu jam kegagalan, alert Webhooks Disabled menyusul dan app dibatalkan langganannya dari Page sampai berlangganan lagi.
- Percobaan ulang bisa mengirim event dua kali dan tidak berurutan, jadi lakukan deduplikasi dan urutkan pesan berdasarkan timestamp-nya.
- Notifikasi lama tidak bisa di-query nanti, jadi simpan yang Anda butuhkan saat notifikasi tiba.
Bagaimana easyCoexistence lolos pemeriksaan Meta?
App Meta-nya memiliki satu callback URL untuk Page yang dihubungkan, dan endpoint itu melakukan kedua pemeriksaan sendiri. Ia menjawab GET hanya jika hub.mode bernilai subscribe dan verify token cocok, dibandingkan dengan waktu konstan, dan mengembalikan 403 jika tidak; ia membaca setiap POST sebagai teks mentah, menghitung ulang X-Hub-Signature-256 dengan app secret miliknya, menolak yang tidak cocok dengan 401, dan segera membalas Meta, lalu memproses event setelah respons.
Bagaimana easyCoexistence menandatangani yang diteruskannya?
Dengan tanda tangan miliknya sendiri, karena header Meta hanya bisa diperiksa dengan app secret easyCoexistence dan tidak diteruskan. Setiap entri untuk Page yang terhubung dan memiliki endpoint dikirim dengan POST ke sana sebagai JSON, {platform, account_id, external_id, entry}, dengan header X-EC-Signature berbentuk t=<unix>,v1=<hex>, di mana v1 adalah HMAC-SHA256 dari timestamp, titik, dan body mentah, dengan kunci signing secret milik Page tersebut:
- Secret diawali whsec_ dan hanya ditampilkan sekali, melalui
set_social_webhook_destinationatau PUT /channels/:id/webhook pada Partner API. - Mengatur ulang URL akan menerbitkan secret baru, dan URL null mematikan peneruskan.
- Setiap peneruskan dikirim sekali, menunggu hingga 8 detik, tanpa mengikuti redirect, ke alamat HTTPS yang di-resolve ke IP publik.
- Tidak ada salinan event yang disimpan, sehingga tidak ada yang bisa dicoba ulang.
Bagaimana memverifikasi X-EC-Signature?
Pisahkan header menjadi t dan v1, tolak timestamp yang lebih dari 5 menit, hitung ulang HMAC atas t, titik, dan body mentah dengan signing secret milik Page, lalu bandingkan dengan waktu konstan. Di Node.js, dengan body disimpan sebagai byte mentah:
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once
app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
);
const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
const expected = crypto
.createHmac("sha256", SECRET)
.update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
.digest("hex");
const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer first: forwards are not retried
const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
// queue entry for the work
});Kesalahan umum
- Membungkus hub.challenge dengan JSON atau tanda kutip. Body dari 200 harus berupa nilai challenge itu sendiri.
- Menghitung HMAC setelah parser JSON. Parsing lalu serialisasi ulang mengubah byte, dan Meta menandatangani payload dengan Unicode di-escape, sehingga hash body mentah.
- Mengerjakan proses sebelum membalas. Messenger mengharapkan 200 dalam 5 detik, dan satu jam kegagalan membatalkan langganan app dari Page.
- Memeriksa tanda tangan Meta pada event yang diteruskan. Meta menandatangani dengan app secret easyCoexistence; event yang diteruskan membawa X-EC-Signature, yang diperiksa dengan signing secret Page.
US$ 9 sampai US$ 0.75 per koneksi per bulan, turun seiring penambahan koneksi, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Dari mana verify token berasal?
Anda yang memilihnya. Itu adalah string yang dimasukkan di kolom Verify Token saat mengonfigurasi webhook di App Dashboard, atau verify_token yang dikirim ke /{app-id}/subscriptions.
Bisakah saya menguji verifikasi dengan curl?
Bisa. Panduan Messenger dari Meta mengirim GET dengan hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED dan hub.mode=subscribe, dan endpoint yang berfungsi menjawab CHALLENGE_ACCEPTED.
Apa yang terjadi jika endpoint saya gagal selama satu jam?
Meta mengirim alert Webhooks Disabled dan membatalkan langganan app dari Page. Setelah memperbaiki endpoint, berlangganan lagi Page melalui subscribed_apps.
Apakah saya memerlukan app Meta sendiri untuk menerima webhook Page?
Tidak dengan easyCoexistence. Meta mengirim ke app-nya, yang meneruskan event setiap Page ke endpoint yang Anda atur, ditandatangani dengan X-EC-Signature.
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