IngiaAnza kipindi cha majaribio bila malipo
easyCoexistence API rasmi

Uthibitishaji wa webhook ya Facebook: hub.challenge na X-Hub-Signature-256

Facebook inathibitisha endpoint ya webhook kwa ombi la GET lenye hub.mode iliyowekwa subscribe, hub.verify_token na hub.challenge; endpoint inalinganisha token na ile iliyo kwenye dashboard ya Meta na kurudisha challenge kama mwili wa jibu. Kisha kila tukio hufika kama POST iliyosainiwa kwenye X-Hub-Signature-256: sha256= ikifuatiwa na HMAC-SHA256 ya payload, ikitumia siri ya programu.

easyCoexistence inashughulikia upande wa Meta kwa kila Ukurasa unaounganisha: programu yake hujibu hub.challenge, hukagua X-Hub-Signature-256 na kujiandikisha kwenye Ukurasa kwa mlisho, jumbe na kutajwa, kisha husambaza matukio kwenye endpoint yako ya HTTPS, yakisainiwa kwa X-EC-Signature na siri ya Ukurasa huo.

subscribe

Thamani ya hub.mode huwa daima subscribe kwenye ombi la uthibitishaji la Meta; hub.challenge ni nambari kamili ya kurudisha.

sha256=

Kiambishi cha X-Hub-Signature-256, kikifuatiwa na sahihi ya SHA256 ambayo Meta huitengeneza kutoka kwenye payload na siri ya programu.

5 seconds

Kasi ambayo endpoint ya webhook ya Messenger inapaswa kujibu kila arifa kwa 200 OK.

1 hour

Idadi ya uwasilishaji ulioshindwa kabla ya arifa ya Webhooks Disabled na programu kuondolewa usajili wa Ukurasa.

36 hours

Muda ambao Meta hujaribu tena arifa ya Ukurasa iliyoshindwa, kwa mzunguko unaopungua, kabla ya kuitupa.

Ombi la uthibitishaji la Meta lina nini?

GET kwenda kwenye URL ya callback, inayotumwa kila wakati bidhaa ya Webhooks inapowekwa kwenye dashboard ya Meta au usajili unapoundwa kupitia /{app-id}/subscriptions. Vigezo vitatu vya swali huambatana nayo:

  • hub.mode: daima subscribe.
  • hub.challenge: nambari kamili ambayo endpoint lazima irudishe.
  • hub.verify_token: mfuatano ulioingizwa kwenye sehemu ya Verify Token ya dashboard.
  • PHP hubadilisha nukta kuwa mistari ya chini, kwa hiyo huyasoma kama hub_mode, hub_challenge na hub_verify_token.

Endpoint inapaswa kujibuje?

Kwa 200 ambayo mwili wake wote ni thamani ya hub.challenge, lakini hiyo tu wakati hub.mode ni subscribe na hub.verify_token inalingana; kitu kingine chochote hupata 403, kama katika programu ya mfano ya Meta. Dashboard inaonyesha kama endpoint imepita, na /{app-id}/subscriptions hujibu kwa mafanikio au hitilafu. Endpoint inahitaji HTTPS yenye cheti halali cha TLS au SSL, kwa kuwa cheti zilizojisainia zenyewe hazikubaliwi.

X-Hub-Signature-256 inahesabiwaje?

Kama HMAC-SHA256 ya payload ya ombi, ikitumia siri ya programu, iliyoandikwa kwa herufi ndogo za hex baada ya sha256=. Mwongozo wa Messenger wa Meta unaongeza kwamba sahihi inahusu payload yenye Unicode iliyotolewa kwa escape, kwa hiyo mfuatano kama äöå unahesabiwa kama \u00e4\u00f6\u00e5: hesabu mwili ghafi kama ulivyopokelewa, kamwe si nakala iliyofumuliwa au iliyoandikwa upya. Meta inasema kuthibitisha ni hiari lakini inapendekeza sana.

Unaikagua vipi kwenye msimbo?

Hifadhi baiti ghafi, hesabu HMAC, linganisha kwa muda usiobadilika, kisha changanua. get_data ya Flask hurudisha mwili bila kuguswa, ambao sahihi ilihesabiwa juu yake; kuufumua kwanza na kuuandika tena kungebadilisha baiti. Endpoint ndogo inayojibu uthibitishaji na kukagua kila 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

Meta inatarajia nini baada ya uthibitishaji?

200 OK kwa kila arifa, ndani ya sekunde 5 kwa matukio ya Messenger. Meta hukusanya hadi masasisho 1,000 kwa kila uwasilishaji bila kuhakikisha hivyo, na hushughulikia hitilafu kwa njia hii:

  • Arifa za Ukurasa: hujaribiwa tena mara moja, kisha mara chache zaidi kwa mzunguko unaopungua ndani ya saa 36, kisha hutupwa.
  • Arifa za Messenger: hujaribiwa tena mara chache mara moja; baada ya dakika 15 za hitilafu, arifa hufika kwenye akaunti ya msanidi programu.
  • Baada ya saa moja ya hitilafu, arifa ya Webhooks Disabled hufuata na programu huondolewa usajili wa Ukurasa hadi ijisajili tena.
  • Majaribio tena yanaweza kuwasilisha tukio mara mbili na nje ya mpangilio, kwa hiyo ondoa marudio, na panga jumbe kwa muhuri wao wa muda.
  • Arifa zilizopita haziwezi kuulizwa baadaye, kwa hiyo hifadhi kile unachohitaji kinapofika.

easyCoexistence inapitisha vipi ukaguzi wa Meta?

Programu yake ya Meta ina URL moja ya callback kwa Kurasa inazounganisha, na endpoint hiyo inafanya ukaguzi wote mawili yenyewe. Inajibu GET tu wakati hub.mode ni subscribe na verify token inalingana, ikilinganishwa kwa muda usiobadilika, na hurudisha 403 vinginevyo; inasoma kila POST kama maandishi ghafi, inahesabu upya X-Hub-Signature-256 kwa siri yake ya programu, inakataa kutofautiana kwa 401, na inamjibu Meta mara moja, ikishughulikia tukio baada ya jibu.

easyCoexistence inasaini vipi kile inachotuma mbele?

Kwa sahihi yake yenyewe, kwa kuwa kichwa cha Meta kinaweza kukaguliwa tu kwa siri ya programu ya easyCoexistence na hakipitishwi. Kila ingizo la Ukurasa uliounganishwa lenye endpoint iliyowekwa hutumwa hapo kwa POST kama JSON, {platform, account_id, external_id, entry}, pamoja na kichwa cha X-EC-Signature chenye umbo t=<unix>,v1=<hex>, ambapo v1 ni HMAC-SHA256 ya muhuri wa muda, nukta na mwili ghafi, ikitumia siri ya kusaini ya Ukurasa huo:

  • Siri huanza na whsec_ na huonyeshwa mara moja, kwa set_social_webhook_destination au PUT /channels/:id/webhook kwenye Partner API.
  • Kuweka URL tena hutoa siri mpya, na URL tupu huzima usambazaji.
  • Kila usambazaji hutumwa mara moja, ukisubiri hadi sekunde 8, bila kufuata uelekezaji upya, kwenda kwenye anwani ya HTTPS inayotatuliwa kuwa IP ya umma.
  • Hakuna nakala ya tukio inayohifadhiwa, kwa hiyo hakuna cha kujaribu tena kutoka.

Unathibitishaje X-EC-Signature?

Gawanya kichwa kuwa t na v1, kataa muhuri wa muda unaozidi dakika 5, hesabu upya HMAC juu ya t, nukta na mwili ghafi kwa siri ya kusaini ya Ukurasa, kisha linganisha kwa muda usiobadilika. Katika Node.js, huku mwili ukihifadhiwa kama baiti ghafi:

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
});

Makosa ya kawaida

  • Kufunga hub.challenge kwenye JSON au nukuu. Mwili wa 200 lazima uwe thamani ya challenge yenyewe.
  • Kuhesabu HMAC baada ya kichanganuzi cha JSON. Kuchanganua na kuandika upya kunabadilisha baiti, na Meta husaini payload yenye Unicode iliyotolewa kwa escape, kwa hiyo hesabu mwili ghafi.
  • Kufanya kazi kabla ya kujibu. Messenger inatarajia 200 ndani ya sekunde 5, na saa moja ya hitilafu huondoa usajili wa programu kwenye Ukurasa.
  • Kukagua sahihi ya Meta kwenye matukio yaliyosambazwa. Meta husaini kwa siri ya programu ya easyCoexistence; tukio lililosambazwa hubeba X-EC-Signature, linalokaguliwa kwa siri ya kusaini ya Ukurasa.
Kufanya hili ukitumia EasyCoexistence

Kuanzia US$ 9 hadi US$ 0.75 kwa muunganisho kwa mwezi, kadri unavyoongeza miunganisho, na siku 3 za kwanza bila malipo.

Maswali yanayoulizwa mara kwa mara

Verify token inatoka wapi?

Wewe unaichagua. Ni mfuatano ulioingizwa kwenye sehemu ya Verify Token unaposanidi webhook kwenye dashboard ya Meta, au verify_token inayotumwa kwa /{app-id}/subscriptions.

Ninaweza kujaribu uthibitishaji kwa curl?

Ndiyo. Mwongozo wa Messenger wa Meta hutuma GET yenye hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED na hub.mode=subscribe, na endpoint inayofanya kazi hujibu CHALLENGE_ACCEPTED.

Nini kitatokea endpoint yangu ikishindwa kwa saa moja?

Meta hutuma arifa ya Webhooks Disabled na kuondoa usajili wa programu kwenye Ukurasa. Baada ya kurekebisha endpoint, jisajili tena Ukurasa kupitia subscribed_apps.

Je, ninahitaji programu yangu ya Meta kupokea webhook za Ukurasa?

Si kwa easyCoexistence. Meta hupeleka kwenye programu yake, ambayo husambaza matukio ya kila Ukurasa kwenye endpoint uliyoweka, yakisainiwa kwa X-EC-Signature.

Endelea kusoma

Unganisha chaneli yako ya kwanza ndani ya dakika mbili.

Hakuna ukaguzi wa majukwaa wa kusubiri. Unganisha WhatsApp, Instagram, TikTok au chaneli nyingine, kisha mwombe AI wako achapishe, ajibu au atoe ripoti, na uone akifanya kazi.

  • Siku 3 bila malipo
  • Ghairi wakati wowote
  • API rasmi pekee
  • Hufuatiliwa saa 24/7

Imethibitishwa kwenye