පුරනය වන්නනොමිලේ trial කාලය ආරම්භ කරන්න
easyCoexistence නිල API

Instagram webhook සත්‍යාපනය: hub.challenge සහ X-Hub-Signature-256

Instagram webhook සැකසීමට, Meta ගේ සත්‍යාපන GET ඉල්ලීමට පිළිතුරු දෙන HTTPS endpoint එකක් අවශ්‍යයි. එම ඉල්ලීමේ hub.mode අගය subscribe වන අතර, එහි hub.verify_token සහ hub.challenge ඇත. Token එක ගැලපේ නම්, challenge අගය ප්‍රතිචාරය ලෙස ආපසු යවන්න. යෙදුම fields වෙත subscribe වූ පසු, සහ සෑම ගිණුමක්ම subscribed_apps edge හරහා subscribe කළ පසු, Meta සිදුවීම් JSON ලෙස POST කරයි, ඒවා X-Hub-Signature-256 හි යෙදුමේ secret සමඟ අත්සන් කර ඇත.

easyCoexistence Meta පැත්ත හසුරුවයි: එහි යෙදුම සත්‍යාපනය සම්මත කරයි, X-Hub-Signature-256 පරීක්ෂා කරයි, සම්බන්ධිත සෑම Instagram ගිණුමක්ම comments, පණිවිඩ සහ mentions වෙත subscribe කරයි, සහ සිදුවීම් ඔබේ HTTPS endpoint එකට X-EC-Signature සහ ගිණුමට අයත් secret එකකින් අත්සන් කර යවයි, සෑම සම්බන්ධතාවයක්ම පැය විසිහතර නිරීක්ෂණය කරමින්.

subscribe

hub.mode අගය Meta ගේ සත්‍යාපන ඉල්ලීමේ සෑම විටම ඇත.

36 hours

Meta අසමත් වූ දැනුම්දීමක් නැවත උත්සාහ කරන කාලය, ඉන් පසු ඉවත් කරන තෙක්, වාර ගණන අඩු වෙමින්.

15 minutes

අසමත් messaging delivery ගණන, Meta සංවර්ධක ගිණුමට අනතුරු ඇඟවීමක් යැවීමට පෙර.

1 hour

Messaging deliveries අසමත් වීමේ ගණන, Webhooks Disabled අනතුරු ඇඟවීම සහ යෙදුමේ ගිණුමෙන් unsubscribe වීම සිදුවීමට පෙර.

Live

Meta ට අවශ්‍ය යෙදුම mode, යෙදුමට පරිශීලකයන්ගේ ගිණුම්වල දැනුම්දීම් ලැබීමට පෙර.

Instagram webhook සැකසීම කෙසේ වැඩ කරයි?

Meta ගේ මාර්ගෝපදේශය දෙන අනුපිළිවෙලට, පියවර හතරකින්. Endpoint එක ක්ෂේත්‍ර තේරීමට පෙර සත්‍යාපනය සම්මත විය යුතුයි, යෙදුම පරිශීලකයන්ගේ ගිණුම් සඳහා දැනුම්දීම් ලැබීමට Live විය යුතුයි, නිෂ්පාදන ප්‍රවේශය සඳහා ව්‍යාපාර සත්‍යාපනය අවශ්‍යයි.

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

සත්‍යාපන ඉල්ලීමේ අන්තර්ගතය කුමක්ද?

Webhooks product එක App Dashboard හි සකසූ විට, callback URL වෙත GET ඉල්ලීමක් යවයි. hub.verify_token එක endpoint එකේම token එක ගැලපුනොත්, පිළිතුර 200 වන අතර, සම්පූර්ණ body එක ලෙස hub.challenge අගය පමණක් ඇත; එසේ නොවුනොත් 403. Dashboard එකෙන් endpoint එක සම්මත වූවාද යන්න පෙන්වයි.

  • hub.mode: සැමවිටම subscribe.
  • hub.challenge: Meta උත්පාදනය කරන පූර්ණ සංඛ්‍යාවක්, endpoint එක ආපසු යැවිය යුතුයි.
  • hub.verify_token: dashboard හි Verify Token ක්ෂේත්‍රයට ඇතුළු කරන string එක, එය Meta සහ endpoint එක පමණක් දැනිය යුතුයි.
  • PHP හි, මෙම නාමවල ඇති තිත යටි ඉර බවට හැරේ, එබැවින් අගයන් hub_mode, hub_challenge සහ 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 සහ fields කොහේ සකසන්නේද?

App Dashboard හි, Instagram, API setup with Instagram login, Configure webhooks යටතේ: callback URL සහ verify token එහි ඇතුළු කරන අතර, ඒවා සුරැකීම සත්‍යාපන ඉල්ලීම ක්‍රියාත්මක කරයි. Instagram නිෂ්පාදනය comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral සහ messaging_seen වලට subscribe වී ආරම්භ වන අතර, Manage මගින් ඒ ඕනෑම එකකින් unsubscribe විය හැක. Test බොත්තම තේරූ field එක සඳහා නියැදි දැනුම්දීමක් යවයි.

X-Hub-Signature-256 පරීක්ෂා කරන්නේ කෙසේද?

Meta සෑම සිදුවීම් දැනුම්දීමක්ම payload එකේ HMAC-SHA256 සමඟ අත්සන් කරයි, යෙදුමේ secret එක යතුර ලෙස භාවිතා කර, එය X-Hub-Signature-256 හි sha256= යනුවෙන් ඉන් පසු hex digest එක ලෙස යවයි. ලබන්නා raw request එකේ body මත එකම HMAC ගණනය කර, constant time ක්‍රමයෙන් header එක සමඟ සසඳයි. Meta ගේ messaging මාර්ගෝපදේශය සටහන් කරන්නේ, අත්සනට Unicode escaped සහිත payload එක ආවරණය වන බැවින්, විකේතනය කළ හෝ නැවත serialize කළ JSON hash කිරීමෙන් වෙනස් ප්‍රතිඵලයක් ලැබෙන බවයි.

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

එය යෙදුමේ secret එකෙන් පමණක් පරීක්ෂා කළ හැක්කේ ඇයි?

මන්ද අත්සන යන්නේ එම secret යතුර ලෙස භාවිතා කරන HMAC එකක් නිසාය. එය නොමැතිව, අපේක්ෂිත අගය ගණනය කළ හැක්කේ කිසිවෙකුටත් නැත, සහ payload එකක පිටපතක් ඇති කිසිවෙකුටත් එය ව්‍යාජ කළ නොහැක, එබැවින් පරීක්ෂාව Meta ගේ ඉල්ලීම් ලබන සේවාදායකයේ තිබිය යුතුයි. Meta ඉල්ලා සිටින්නේ යෙදුමේ secret, access token සහ client credentials logs සහ සහාය ඉල්ලීම්වලින් බැහැරව තබන ලෙසයි. වෙනත් යෙදුමකින් යවන ලද සිදුවීම් ලබන පද්ධතියකට Meta ගේ අත්සන පරීක්ෂා කළ නොහැක, ඒ වෙනුවට එම යෙදුමේ අත්සනට විශ්වාසය තැබිය යුතුයි.

සෑම ගිණුමකටම වෙනම දායකත්වයක් අවශ්‍ය වන්නේ ඇයි?

මන්ද App Dashboard මගින් යෙදුමට ලැබිය හැක්කේ කුමක්ද යන්න සකසන අතර, ගිණුමක දැනුම්දීම් ආරම්භ වන්නේ එම ගිණුමද subscribe වූ පසුව පමණි. Instagram Login සමඟ, ගිණුමේ Instagram User access token සහ යෙදුම සඳහා තෝරාගත් fields comma මගින් වෙන් කර ලැයිස්තුගත කරමින්, POST /<IG_ID>/subscribed_apps graph.instagram.com වෙත යවන්න. සාර්ථක ඉල්ලීමක් success අගය 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 අසමත් වූ විට කුමක් කරයිද?

එය නැවත උත්සාහ කර, පසුව අත්හරියි. Meta ගේ මාර්ගෝපදේශය සෑම දැනුම්දීමකටම 200 OK ඉල්ලා සිටින අතර, update 1,000ක් දක්වා කණ්ඩායම් කිරීම (batching) සහතික නොවන බව අනතුරු ඇඟවීමක් ලෙස සඳහන් කරයි. අසමත් update එකක් වහාම නැවත උත්සාහ වන අතර, පසුව පැය 36ක් මත වාර ගණන අඩු වෙමින් තව කිහිපවරක් උත්සාහ වන අතර, ඉන් පසු ඉවත් වේ; එබැවින් එකම සිදුවීම දෙවරක් ලැබිය හැක. Messaging සිදුවීම් Meta ගේ messaging delivery නීති අනුගමනය කරන අතර, ඒවා වඩා වේගවත් ක්‍රියා කරයි:

  • 200 OK තත්පර 5ක් ඇතුළත බලාපොරොත්තු වන අතර, අසමත් delivery එකකට වහාම retry කිහිපයක් ලැබේ, එබැවින් message mid මත අනුපිටපත් ඉවත් කරන්න.
  • විනාඩි 15ක අසමත්වීමකට පසු, සංවර්ධක ගිණුමට අනතුරු ඇඟවීමක් යයි.
  • පැයක අසමත්වීමකට පසු, Webhooks Disabled අනතුරු ඇඟවීමක් ලැබෙන අතර, ගිණුමේ webhooks වෙතින් යෙදුම නැවත subscribe වන තෙක් unsubscribe වේ.
  • Outage අතරතුර යවන ලද පණිවිඩ පිළිවෙලින් නොපැමිණිය හැක, එබැවින් ඒවා timestamp අනුව තබා ගන්න.

කිසිවක් නොපැමිණෙන විට කුමක් පරීක්ෂා කළ යුතුද?

Meta ගේ දෝෂ නිරාකරණ ලැයිස්තුව, බොහෝ නිශ්ශබ්ද endpoint ආවරණය කරමින්, මේ අනුපිළිවෙලින්:

  • Callback URL එක එහි පරීක්ෂාව සමත් වී ඇති අතර HTTPS හරහා වලංගු certificate එකක් සමඟ ප්‍රවේශ විය හැක; self-signed ඒවා සහාය නොදක්වයි.
  • යෙදුම field එක තෝරාගෙන ඇති අතර ඒ සඳහා අවශ්‍ය access level ඇත, comments සහ live_comments සඳහා Advanced Access.
  • subscribed_apps හරහා ගිණුම සඳහා දැනුම්දීම් සක්‍රීය කර ඇත, එකම login සැකසීමේ token එකක් සමඟ.
  • ගිණුම field හි නීතිවලට අනුකූලයි: comment දැනුම්දීම් සඳහා public ගිණුමකට අයත් media අවශ්‍යයි.
  • Server එක, මන්දගාමී වැඩ ආරම්භ කිරීමට පෙර, success ප්‍රතිචාරය ලබා දෙයි.

easyCoexistence ගෙන් යවන සිදුවීම් නැවත අත්සන් කරන්නේ ඇයි?

මන්ද Meta ගේ අත්සනට ගමන් කළ නොහැක. easyCoexistence ගේ යෙදුම Meta ගේ delivery ලබා, එහි තමන්ගේ යෙදුමේ secret සමඟ X-Hub-Signature-256 පරීක්ෂා කර, Meta ට වහාම පිළිතුරු දෙන අතර, සම්බන්ධිත ගිණුමක සෑම entry එකක්ම එම ගිණුම සඳහා සකසා ඇති endpoint වෙත POST කරයි, platform, account_id, external_id සහ entry අඩංගු නව body එකක. Meta ගේ header එක ඉදිරියට යවන්නේ නැති අතර, එම secret නොමැතිව පරීක්ෂා කළ නොහැක, එබැවින් සෑම යැවීමකම Content-Type: application/json සහ X-EC-Signature ඇති අතර, එය එක් ගිණුමකට අයත් secret එකකින් යතුරු ලබා දේ.

X-EC-Signature පරීක්ෂා කරන්නේ කෙසේද?

Header එක t=<unix>,v1=<hex> ලෙස කියවන අතර, v1 යනු timestamp, dot සහ raw body එක මත hex HMAC-SHA256 වන අතර, ගිණුමේ signing secret එකෙන් යතුරු ලබා දේ. ලැබුණු ආකාරයටම bytes මත නැවත ගණනය කර, constant time ක්‍රමයෙන් සසඳා, මිනිත්තු 5ට වඩා පැරණි timestamp එකක් ප්‍රතික්ෂේප කරන්න.

  • Secret එක whsec_ න් ආරම්භ වන අතර, URL සකසන විට set_social_webhook_destination හෝ PUT /channels/:id/webhook මගින් එක් වරක් පෙන්වයි.
  • URL නැවත සැකසීම නව secret එකක් නිකුත් කරන අතර, null URL එකක් forwarding නිවා දමයි.
  • සෑම සිදුවීමක්ම එක් වරක් යවන අතර, තත්පර 8ක් දක්වා රැඳී සිටී, redirects අනුගමනය නොකර, public IP වෙත විසඳෙන HTTPS ලිපිනයකට.
  • සම්බන්ධතාවය ඉවත් කිරීම ගිණුම Meta ගේ webhooks වෙතින් unsubscribe කර, එහි endpoint සහ secret මකා දමයි.
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())

සාමාන්‍ය වැරදි

  • Challenge එක JSON ලෙස හෝ උධෘත ලකුණු තුළ ආපසු යැවීම. Meta බලාපොරොත්තු වන්නේ hub.challenge අගයම body එක ලෙස, 200 status සමඟ ය.
  • Parsed body එක hash කිරීම. JSON body parser එකක් Meta අත්සන් කළ නිශ්චිත bytes ඉවත් කරයි, එබැවින් HMAC සඳහා raw body එක තබා ගෙන පසුව parse කරන්න.
  • යෙදුම subscribe කර ගිණුම අමතක කිරීම. POST /<IG_ID>/subscribed_apps එක ගිණුමක් සඳහා සාර්ථක වන තෙක්, එම ගිණුම සඳහා දැනුම්දීම් නොපැමිණේ.
  • Endpoint එකක් පැයක් පුරා අසමත් වීමට ඉඩ දීම. Meta messaging webhooks අක්‍රිය කර, යෙදුම ගිණුමෙන් unsubscribe කරයි, ඉන් පසු නැවත subscribe කළ යුතුයි.
EasyCoexistence සමඟ මෙය කිරීම

set_social_webhook_destination හෝ Partner API මගින් ක්‍රියාත්මක කරන්න. සම්බන්ධතාවයකට මාසිකව US$ 9 සිට US$ 0.75 දක්වා, සම්බන්ධතා එකතු කරන විට අඩු වෙමින්, පළමු දින 3 trial කාලය නොමිලේ.

නිතර අසන ප්‍රශ්න

Instagram webhook හි hub.challenge යනු කුමක්ද?

Meta ගේ සත්‍යාපන GET හි එවන පූර්ණ සංඛ්‍යාවකි. hub.verify_token පරීක්ෂා කළ පසු endpoint එක එය response body ලෙස ආපසු දෙයි, එමගින් එය URL එක පාලනය කරන බව ඔප්පු කරයි.

PHP හි hub.mode සහ hub.challenge නොමැත්තේ ඇයි?

PHP parameter නාමවල තිත් යටි ඉරවලට හරවයි, එබැවින් Meta ගේ සත්‍යාපන අගයන් hub_mode, hub_challenge සහ hub_verify_token ලෙස ලැබේ.

Meta ඒවා අක්‍රිය කළ පසු Instagram webhooks නැවත ක්‍රියාත්මක කරන්නේ කෙසේද?

Endpoint එක නිවැරදි කර, පසුව එම fields සමඟ POST /<IG_ID>/subscribed_apps මගින් ගිණුම නැවත subscribe කරන්න.

Self-signed certificate එකක් Instagram webhook endpoint එකට ක්‍රියා කරයිද?

නැත, Meta self-signed certificates සහාය නොදක්වයි: callback URL එක HTTPS හරහා වලංගු certificate එකක් සමඟ ප්‍රවේශ විය යුතුයි, එය Meta ගේ දෝෂ නිරාකරණ ලැයිස්තුවේ පළමු අයිතමයයි.

තවදුරටත් කියවන්න

ඔබේ පළමු channel එක මිනිත්තු දෙකකින් සම්බන්ධ කරන්න.

වේදිකා සමාලෝචන සඳහා බලා සිටීමට අවශ්‍ය නැත. WhatsApp, Instagram, TikTok හෝ වෙනත් channel එකක් සම්බන්ධ කර, පසුව ඔබේ AI හට පළ කිරීමට, ප්‍රතිචාර දැක්වීමට හෝ වාර්තා කිරීමට පවසා එය වැඩ කරන ආකාරය බලන්න.

  • දින 3ක් නොමිලේ
  • ඕනෑම වේලාවක අවලංගු කරන්න
  • නිල API පමණි
  • 24/7 නිරීක්ෂණය කෙරේ

සත්‍යාපනය කළේ