IngiaAnza kipindi cha majaribio bila malipo
easyCoexistence API rasmi

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

Kuweka webhook za Instagram kunahitaji endpoint ya HTTPS inayojibu ombi la GET la uthibitishaji la Meta, lenye hub.mode yenye thamani subscribe, hub.verify_token na hub.challenge. Endpoint hukagua token na kurudisha thamani ya hub.challenge. Kisha Meta hutuma matukio ya JSON yaliyosainiwa kwa X-Hub-Signature-256 kwa siri ya programu, baada ya programu kujisajili kwenye sehemu za data na kila akaunti kujisajili kupitia subscribed_apps edge yake.

easyCoexistence inashughulikia upande wa Meta: programu yake hupitia uthibitishaji, hukagua X-Hub-Signature-256, hujisajili kwa maoni, ujumbe na kutajwa kwa kila akaunti ya Instagram iliyounganishwa, na husambaza matukio kwenye endpoint yako ya HTTPS ikisainiwa kwa X-EC-Signature na siri kwa kila akaunti, pamoja na ufuatiliaji wa saa 24 wa kila muunganisho.

subscribe

Thamani ya hub.mode huwa daima kwenye ombi la uthibitishaji la Meta.

36 hours

Muda ambao Meta hujaribu tena arifa iliyoshindwa, kwa mara chache zinazopungua kadri muda unavyoenda, kabla ya kuiondoa.

15 minutes

Idadi ya uwasilishaji wa ujumbe ulioshindwa kabla Meta haijatuma tahadhari kwenye akaunti ya msanidi programu.

1 hour

Idadi ya uwasilishaji wa ujumbe unaoshindwa kabla ya tahadhari ya Webhooks Disabled na programu kujiondoa kwenye akaunti.

Live

Hali ya programu ambayo Meta inahitaji kabla programu haijapokea arifa za akaunti za watumiaji wake, yaani hali ya Live.

Kuweka webhook za Instagram hufanyika vipi?

Kwa hatua nne, kwa mpangilio ambao mwongozo wa Meta unatoa. Endpoint lazima ipite uthibitishaji kabla sehemu yoyote haijachaguliwa, programu lazima iwe kwenye hali ya Live ili ipokee arifa za akaunti za watumiaji wake, na uthibitishaji wa biashara unahitajika kwa ufikiaji wa uzalishaji.

1EndpointAn HTTPS URL with a valid certificate answers the verification GET
2App fieldsCallback URL, verify token and fields set in the App Dashboard
3Each accountPOST /<IG_ID>/subscribed_apps turns its notifications on
4TestA dashboard test, then a real event, reach the endpoint

Ombi la uthibitishaji lina nini?

GET kwenda kwenye callback URL, inayotumwa kila wakati Webhooks inapowekwa kwenye dashboard ya programu. Hub.verify_token inapolingana na token ya endpoint yenyewe, jibu ni 200 lenye thamani ya hub.challenge kama mwili mzima wa jibu; vinginevyo ni 403. Dashboard huonyesha kama endpoint ilipita.

  • hub.mode: daima subscribe.
  • hub.challenge: nambari kamili ambayo Meta huitengeneza, ambayo endpoint lazima irudishe.
  • hub.verify_token: mfuatano unaoingizwa kwenye sehemu ya Verify Token ya dashboard, ambao Meta na endpoint pekee zinapaswa kuujua.
  • Kwa PHP, nukta kwenye majina haya hubadilika kuwa mistari ya chini, kwa hivyo thamani hufika kama hub_mode, hub_challenge na hub_verify_token.
The verification request and its answer
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

1158201444

Callback na sehemu zimewekwa wapi?

Kwenye dashboard ya programu, chini ya Instagram, API setup with Instagram login, Configure webhooks: callback URL na verify token huwekwa hapo, na kuzihifadhi huanzisha ombi la uthibitishaji. Bidhaa ya Instagram huanza ikiwa imejisajili kwenye comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral na messaging_seen, na Manage huondoa usajili wa yoyote kati yao. Kitufe cha Test hutuma arifa ya mfano kwa sehemu iliyochaguliwa.

X-Hub-Signature-256 inakaguliwaje?

Meta husaini kila arifa ya tukio kwa HMAC-SHA256 ya payload, ikifungwa kwa siri ya programu, na kuituma kwenye X-Hub-Signature-256 kama sha256= ikifuatiwa na digest ya hex. Mpokeaji huhesabu HMAC ile ile juu ya mwili ghafi wa ombi na kuilinganisha, kwa muda usiobadilika, na kichwa cha ombi. Mwongozo wa uwasilishaji wa ujumbe wa Meta unaeleza kwamba sahihi hufunika payload pamoja na Unicode iliyotolewa kwa escape, kwa hivyo kuhesabu hash ya JSON iliyochambuliwa au kuandikwa upya hutoa matokeo tofauti.

Node.js: answering verification and checking X-Hub-Signature-256
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);

Kwa nini siri ya programu pekee inaweza kuikagua?

Kwa sababu sahihi ni HMAC iliyofungwa kwa siri hiyo. Bila hiyo, hakuna anayeweza kuhesabu thamani inayotarajiwa, na hakuna anayeshika nakala ya payload anayeweza kuighushi, kwa hivyo ukaguzi lazima uwe kwenye seva inayopokea maombi ya Meta kwa programu. Meta inaomba kwamba siri za programu, token za ufikiaji na vitambulisho vya client visiwe kwenye kumbukumbu wala kwenye maombi ya msaada. Mfumo unaopokea matukio yaliyopitishwa na programu nyingine hauwezi kukagua sahihi ya Meta hata kidogo, na hutegemea sahihi ya programu hiyo yenyewe badala yake.

Kwa nini kila akaunti inahitaji usajili wake?

Kwa sababu dashboard ya programu huweka kile programu inachoweza kupokea, na arifa za akaunti huanza tu akaunti hiyo inapojisajili pia. Kwa Instagram Login, tuma POST /<IG_ID>/subscribed_apps kwenda graph.instagram.com pamoja na token ya ufikiaji ya Instagram User ya akaunti, na subscribed_fields inayoorodhesha sehemu zilizochaguliwa kwa programu, zikitenganishwa kwa koma. Mwito uliofaulu hurudisha success ikiwa imewekwa kuwa true.

Subscribing one account to comments and messages
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

Meta hufanya nini uwasilishaji unaposhindwa?

Hujaribu tena, kisha huacha. Mwongozo wa Meta unaomba 200 OK kwa kila arifa na unaonya kwamba kukusanya masasisho hadi 1,000 pamoja hakuhakikishwi. Sasisho lililoshindwa hujaribiwa tena mara moja, kisha mara chache zaidi kwa mzunguko unaopungua ndani ya saa 36, na kisha hutupwa, kwa hivyo tukio lile lile linaweza kufika mara mbili. Matukio ya ujumbe hufuata kanuni za uwasilishaji wa ujumbe za Meta, ambazo hutenda haraka zaidi:

  • 200 OK inatarajiwa ndani ya sekunde 5, na uwasilishaji ulioshindwa hupata marudio ya haraka machache, kwa hivyo ondoa marudufu kwa kutumia mid ya ujumbe.
  • Baada ya dakika 15 za kushindwa, tahadhari hutumwa kwenye akaunti ya msanidi programu.
  • Baada ya saa moja ya kushindwa, tahadhari ya Webhooks Disabled hufuata, na programu inaondolewa kwenye webhooks za akaunti hadi ijisajili tena.
  • Ujumbe uliotumwa wakati wa hitilafu unaweza kufika nje ya mpangilio, kwa hivyo upange kwa timestamp ya kila tukio.

Ukiona hakuna kinachofika, cha kukagua ni nini?

Orodha ya ukaguzi ya utatuzi ya Meta, inayofunika endpoint nyingi zisizojibu, kwa mpangilio huu:

  • Callback URL ilipita ukaguzi wake na inafikika kwa HTTPS yenye cheti halali; vyeti vilivyojisaini vyenyewe havitumiki.
  • Programu ilichagua sehemu hiyo na ina kiwango cha ufikiaji inachohitaji, Advanced Access kwa comments na live_comments.
  • Arifa zimewezeshwa kwa akaunti kupitia subscribed_apps, kwa token kutoka usanidi uleule wa kuingia.
  • Akaunti inatimiza kanuni za sehemu hiyo: arifa za maoni zinahitaji media inayomilikiwa na akaunti ya umma.
  • Seva hurudisha success kabla ya kuanza kazi nzito.

Kwa nini easyCoexistence husaini tena matukio yanayosambazwa?

Kwa sababu sahihi ya Meta haiwezi kusafiri. Programu ya easyCoexistence hupokea uwasilishaji wa Meta, hukagua X-Hub-Signature-256 kwa siri yake ya programu, hujibu Meta mara moja, na hutuma kila entry ya akaunti iliyounganishwa kwenda kwenye endpoint iliyowekwa kwa akaunti hiyo, ndani ya mwili mpya wenye platform, account_id, external_id na entry. Kichwa cha Meta hakipitishwi wala kisingeweza kukaguliwa bila siri hiyo, kwa hivyo kila usambazaji hubeba Content-Type: application/json na X-EC-Signature, iliyofungwa kwa siri inayomilikiwa na akaunti hiyo moja.

Unathibitishaje X-EC-Signature?

Kichwa kinasomeka t=<unix>,v1=<hex>, ambapo v1 ni HMAC-SHA256 ya hex ya timestamp, nukta, na mwili ghafi, ikifungwa kwa siri ya kusaini ya akaunti. Hesabu upya juu ya baiti kama zilivyopokelewa hasa, linganisha kwa muda usiobadilika, na ukatae timestamp yenye zaidi ya dakika 5.

  • Siri huanza na whsec_ na huonyeshwa mara moja tu, na set_social_webhook_destination au PUT /channels/:id/webhook URL inapowekwa.
  • Kuweka URL tena hutoa siri mpya, na URL tupu (null) huzima usambazaji.
  • Kila tukio hutumwa mara moja, kwa kusubiri hadi sekunde 8, bila kufuata uelekezaji upya, kwenda anwani ya HTTPS inayotatuliwa kuwa IP ya umma.
  • Kuondoa muunganisho kunaondoa usajili wa akaunti kwenye webhooks za Meta na kufuta endpoint yake na siri yake.
Python: checking X-EC-Signature
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())

Makosa ya kawaida

  • Kurudisha challenge kama JSON au ndani ya nukuu. Meta inatarajia thamani ya hub.challenge yenyewe kama mwili, na hali ya 200.
  • Kuhesabu hash ya mwili uliochambuliwa. Kichambuzi cha mwili wa JSON hutupa baiti kamili ambazo Meta ilisaini, kwa hivyo hifadhi mwili ghafi kwa HMAC kisha uchambue baadaye.
  • Kujisajili kwenye programu na kusahau akaunti. Hadi POST /<IG_ID>/subscribed_apps ifanikiwe kwa akaunti, hakuna arifa zitakazofika kwake.
  • Kuruhusu endpoint kushindwa kwa saa moja. Meta huzima webhooks za ujumbe na kuondoa usajili wa programu kwenye akaunti, ambayo kisha inapaswa kujisajili tena.
Kufanya hili ukitumia EasyCoexistence

Iwashe kwa set_social_webhook_destination au Partner API. Kuanzia US$ 9 hadi US$ 0.75 kwa kila muunganisho kwa mwezi, bei ikishuka kadri unavyoongeza muunganisho, pamoja na kipindi cha majaribio bila malipo cha siku 3 za kwanza.

Maswali yanayoulizwa mara kwa mara

hub.challenge ni nini kwenye webhook za Instagram?

Nambari kamili ambayo Meta hutuma kwenye ombi lake la GET la uthibitishaji. Baada ya kukagua hub.verify_token, endpoint huirudisha kama mwili wa jibu, na hivyo kuthibitisha kwamba inadhibiti URL hiyo.

Kwa nini hub.mode na hub.challenge hazionekani kwenye PHP?

PHP hubadilisha nukta kwenye majina ya vigezo kuwa mistari ya chini, kwa hivyo thamani za uthibitishaji za Meta hufika kama hub_mode, hub_challenge na hub_verify_token.

Nifanyeje kuwasha tena webhook za Instagram baada ya Meta kuzizima?

Rekebisha endpoint, kisha jisajili tena akaunti kwa POST /<IG_ID>/subscribed_apps na sehemu zilezile.

Je, cheti kilichojisaini chenyewe kinafanya kazi kwa endpoint ya webhook ya Instagram?

Hapana, Meta haiungi mkono vyeti vilivyojisaini vyenyewe: callback URL lazima ifikike kwa HTTPS yenye cheti halali, kipengee cha kwanza kwenye orodha ya ukaguzi wa utatuzi ya Meta.

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