Log masukMulakan percubaan percuma
easyCoexistence API rasmi

Verifikasi webhook Facebook: hub.challenge dan X-Hub-Signature-256

Facebook mengesahkan endpoint webhook melalui permintaan GET yang membawa hub.mode bernilai subscribe, hub.verify_token dan hub.challenge; endpoint menyemak token itu dengan token dalam App Dashboard dan memulangkan nilai hub.challenge sebagai badan respons. Setiap acara kemudian tiba sebagai POST yang ditandatangani dalam X-Hub-Signature-256: sha256= diikuti HMAC-SHA256 payload, dikunci dengan App Secret.

easyCoexistence mengendalikan bahagian Meta bagi setiap Page yang anda sambungkan: aplikasinya membalas hub.challenge, menyemak X-Hub-Signature-256 dan melanggan Page kepada suapan, mesej dan sebutan, kemudian memajukan acara ke endpoint HTTPS anda yang ditandatangani dengan X-EC-Signature dan secret bagi Page itu.

subscribe

Nilai hub.mode sentiasa dibawa dalam permintaan pengesahan Meta; hub.challenge ialah integer yang perlu dipulangkan semula.

sha256=

Awalan X-Hub-Signature-256, diikuti tandatangan SHA256 yang dijana Meta daripada payload dan App Secret.

5 seconds

Berapa pantas endpoint webhook Messenger perlu membalas setiap pemberitahuan dengan 200 OK.

1 hour

Bilangan penghantaran gagal sebelum amaran Webhooks Disabled dan aplikasi dinyahlanggan daripada Page.

36 hours

Berapa lama Meta mencuba semula pemberitahuan Page yang gagal, dengan kekerapan yang semakin berkurang, sebelum membuangnya.

Apakah yang terkandung dalam permintaan pengesahan Meta?

Satu GET ke URL panggil balik, dihantar setiap kali produk Webhooks dikonfigurasi dalam App Dashboard atau langganan dicipta melalui /{app-id}/subscriptions. Tiga parameter query disertakan:

  • hub.mode: sentiasa subscribe.
  • hub.challenge: integer yang mesti dipulangkan oleh endpoint.
  • hub.verify_token: rentetan yang dimasukkan dalam medan Verify Token di dashboard.
  • PHP menukar titik kepada sengkang bawah, jadi ia membacanya sebagai hub_mode, hub_challenge dan hub_verify_token.

Bagaimana endpoint sepatutnya membalasnya?

Dengan 200 yang keseluruhan badannya ialah nilai hub.challenge, tetapi hanya apabila hub.mode ialah subscribe dan hub.verify_token sepadan; apa-apa lain menerima 403, seperti dalam aplikasi contoh Meta. Dashboard melaporkan sama ada endpoint lulus, dan /{app-id}/subscriptions membalas dengan kejayaan atau ralat. Endpoint memerlukan HTTPS dengan sijil TLS atau SSL yang sah, kerana sijil yang ditandatangani sendiri tidak disokong.

Bagaimana X-Hub-Signature-256 dikira?

Sebagai HMAC-SHA256 bagi payload permintaan yang dikunci dengan App Secret aplikasi, ditulis dalam hex huruf kecil selepas sha256=. Panduan Messenger Meta menambah bahawa tandatangan itu meliputi payload dengan Unicode yang di-escape, jadi rentetan seperti äöå dikira sebagai \u00e4\u00f6\u00e5: hash badan mentah tepat seperti yang diterima, bukan salinan yang telah dinyahkodkan atau disirikan semula. Meta menyatakan pengesahan adalah pilihan, tetapi amat disyorkan.

Bagaimana anda menyemaknya dalam kod?

Simpan bait mentah, kira HMAC, bandingkan dalam masa tetap, kemudian hurai. get_data Flask memulangkan badan tanpa diubah, iaitu yang tandatangan dikira ke atasnya; menghuraikannya dahulu dan menyirikannya semula akan mengubah bait. Endpoint kecil yang membalas pengesahan dan menyemak setiap POST:

Python: hub.challenge and X-Hub-Signature-256
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", 200

Apa yang Meta jangkakan selepas pengesahan?

200 OK bagi setiap pemberitahuan, dalam masa 5 saat untuk acara Messenger. Meta mengumpulkan sehingga 1,000 kemas kini bagi setiap penghantaran tanpa menjaminnya, dan mengendalikan kegagalan dengan cara ini:

  • Pemberitahuan Page: dicuba semula serta-merta, kemudian beberapa kali lagi dengan kekerapan yang semakin berkurang sepanjang 36 jam, kemudian dibuang.
  • Pemberitahuan Messenger: dicuba semula beberapa kali serta-merta; selepas 15 minit kegagalan, amaran sampai ke akaun pembangun.
  • Selepas sejam kegagalan, amaran Webhooks Disabled menyusul dan aplikasi dinyahlanggan daripada Page sehingga ia melanggan semula.
  • Cubaan semula boleh menghantar acara dua kali dan tidak mengikut susunan, jadi nyahduplikasi dan susun mesej mengikut cap masa.
  • Pemberitahuan lalu tidak boleh ditanya kemudian, jadi simpan apa yang anda perlukan semasa ia tiba.

Bagaimana easyCoexistence lulus semakan Meta?

Aplikasi Meta miliknya mempunyai satu URL panggil balik bagi Page yang disambungkannya, dan endpoint itu melakukan kedua-dua semakan sendiri. Ia membalas GET hanya apabila hub.mode ialah subscribe dan verify token sepadan, dibandingkan dalam masa tetap, dan memulangkan 403 jika tidak; ia membaca setiap POST sebagai teks mentah, mengira semula X-Hub-Signature-256 dengan App Secret-nya, menolak ketidakpadanan dengan 401, dan membalas Meta serta-merta, mengendalikan acara selepas respons.

Bagaimana easyCoexistence menandatangani apa yang dimajukannya?

Dengan tandatangan sendiri, kerana header Meta hanya boleh disemak dengan App Secret easyCoexistence dan tidak diteruskan. Setiap entri bagi Page yang disambungkan dengan endpoint ditetapkan dihantar ke sana sebagai JSON, {platform, account_id, external_id, entry}, dengan header X-EC-Signature dalam bentuk t=<unix>,v1=<hex>, dengan v1 ialah HMAC-SHA256 bagi cap masa, titik dan badan mentah, dikunci dengan signing secret Page itu:

  • Secret bermula dengan whsec_ dan ditunjukkan sekali sahaja, melalui set_social_webhook_destination atau PUT /channels/:id/webhook pada Partner API.
  • Menetapkan URL semula mengeluarkan secret baharu, dan URL null mematikan pemajuan.
  • Setiap pemajuan dihantar sekali sahaja, menunggu sehingga 8 saat, tanpa mengikut ubah hala, ke alamat HTTPS yang diselesaikan kepada IP awam.
  • Tiada salinan acara disimpan, jadi tiada apa untuk dicuba semula.

Bagaimana anda mengesahkan X-EC-Signature?

Pisahkan header kepada t dan v1, tolak cap masa yang berusia lebih 5 minit, kira semula HMAC ke atas t, titik dan badan mentah dengan signing secret Page, dan bandingkan dalam masa tetap. Dalam Node.js, dengan badan dikekalkan sebagai bait mentah:

Node.js: checking X-EC-Signature on a forwarded event
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
});

Kesilapan biasa

  • Membungkus hub.challenge dalam JSON atau tanda petik. Badan 200 mesti nilai hub.challenge itu sendiri.
  • Mengira HMAC selepas penghurai JSON. Menghurai dan menyirikan semula mengubah bait, dan Meta menandatangani payload dengan Unicode yang di-escape, jadi hash badan mentah.
  • Melakukan kerja sebelum membalas. Messenger menjangka 200 dalam masa 5 saat, dan sejam kegagalan menyahlanggankan aplikasi daripada Page.
  • Menyemak tandatangan Meta pada acara yang dimajukan. Meta menandatangani dengan App Secret easyCoexistence; acara yang dimajukan membawa X-EC-Signature, disemak dengan signing secret Page.
Menggunakan EasyCoexistence untuk ini

Daripada US$ 9 hingga US$ 0.75 setiap sambungan sebulan, berkurang apabila anda menambah sambungan, dengan 3 hari pertama percuma.

Soalan lazim

Dari mana token pengesahan datang?

Anda yang memilihnya. Ia ialah rentetan yang dimasukkan dalam medan Verify Token semasa mengkonfigurasi webhook dalam App Dashboard, atau verify_token yang dihantar ke /{app-id}/subscriptions.

Bolehkah saya menguji pengesahan dengan curl?

Boleh. Panduan Messenger Meta menghantar GET dengan hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED dan hub.mode=subscribe, dan endpoint yang berfungsi membalas CHALLENGE_ACCEPTED.

Apa berlaku jika endpoint saya gagal selama sejam?

Meta menghantar amaran Webhooks Disabled dan menyahlanggan aplikasi daripada Page. Selepas membetulkan endpoint, langgan Page semula melalui subscribed_apps.

Adakah saya perlukan aplikasi Meta sendiri untuk menerima webhook Page?

Tidak dengan easyCoexistence. Meta menghantar kepada aplikasinya, yang memajukan acara setiap Page ke endpoint yang anda tetapkan, ditandatangani dengan X-EC-Signature.

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