Mag-log inMagsimula ng Libreng Trial
easyCoexistence Mga Official API

Instagram webhook verification: hub.challenge at X-Hub-Signature-256

Ang pag-set up ng Instagram webhooks ay nangangailangan ng HTTPS endpoint na sumasagot sa verification GET ng Meta, na may kasamang hub.mode na naka-set sa subscribe, hub.verify_token, at hub.challenge, sa pamamagitan ng pag-check sa token at pagbabalik ng challenge. Pagkatapos, nagpapadala ang Meta ng JSON events na naka-sign sa X-Hub-Signature-256 gamit ang secret ng app, kapag na-subscribe na ng app ang mga field at bawat account sa pamamagitan ng subscribed_apps edge nito.

Inaasikaso ng easyCoexistence ang panig ng Meta: pumapasa ang app nito sa verification, sinusuri ang X-Hub-Signature-256, sina-subscribe ang bawat naka-connect na Instagram account sa comments, mensahe at mentions, at ipinapasa ang mga event sa inyong HTTPS endpoint na naka-sign ng X-EC-Signature at may hiwalay na secret kada account, habang binabantayan ang bawat koneksyon sa buong araw at gabi.

subscribe

Palaging may dalang value na hub.mode ang verification request ng Meta.

36 hours

Panahon kung kailan inuulit ng Meta ang pagpapadala ng nabigong notification, na may bumababang dalas, bago ito tuluyang alisin.

15 minutes

Ng nabibigong messaging delivery bago magpadala ang Meta ng alert sa developer account.

1 hour

Ng sunod-sunod na nabibigong messaging delivery bago lumabas ang alert na Webhooks Disabled at ma-unsubscribe ang app sa account.

Live

App mode na kailangan ng Meta bago makatanggap ng notifications ang app para sa mga account ng mga user nito.

Paano gumagana ang pag-set up ng Instagram webhooks?

Sa apat na hakbang, ayon sa pagkakasunod-sunod na ibinigay ng gabay ng Meta. Kailangang pumasa muna sa verification ang endpoint bago mapili ang anumang field, kailangang Live ang app para makatanggap ng notifications para sa mga account ng mga user nito, at kailangan ang pagve-verify ng negosyo para sa production access.

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

Ano ang laman ng verification request?

Isang GET sa callback URL, na ipinapadala tuwing naka-configure ang Webhooks product sa App Dashboard. Kapag tumugma ang hub.verify_token sa sariling token ng endpoint, ang sagot ay 200 na may value ng hub.challenge bilang buong body; kung hindi, 403. Ipinapakita ng dashboard kung pumasa ang endpoint.

  • hub.mode: palaging subscribe.
  • hub.challenge: isang integer na ginagawa ng Meta, na dapat ibalik ng endpoint.
  • hub.verify_token: ang string na inilagay sa Verify Token field ng dashboard, na dapat alam lang ng Meta at ng endpoint.
  • Sa PHP, nagiging underscore ang mga tuldok sa mga pangalang ito, kaya dumarating ang mga value bilang hub_mode, hub_challenge at 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

Saan itinatakda ang callback at ang mga field?

Sa App Dashboard, sa ilalim ng Instagram, API setup with Instagram login, Configure webhooks: doon ilalagay ang callback URL at verify token, at ang pag-save nito ang magpapatakbo ng verification request. Nagsisimula ang Instagram product na naka-subscribe sa comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral at messaging_seen, at maaaring i-unsubscribe ng Manage ang alinman sa mga ito. Nagpapadala ang Test button ng sample notification para sa napiling field.

Paano sinusuri ang X-Hub-Signature-256?

Pinipirmahan ng Meta ang bawat event notification gamit ang HMAC-SHA256 ng payload, na ginagamitan ng secret ng app, at ipinapadala ito sa X-Hub-Signature-256 bilang sha256= kasunod ng hex digest. Kinukuwenta ng receiver ang parehong HMAC sa raw request body at inihahambing ito sa header, sa constant time. Sinasabi ng gabay ng Meta sa messaging na sakop ng signature ang payload na may escaped na Unicode, kaya ang pag-hash ng na-decode o muling na-serialize na JSON ay nagbibigay ng ibang resulta.

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

Bakit ang secret lang ng app ang makakapag-check nito?

Dahil ang signature ay isang HMAC na may susi na ang secret na iyon. Kapag wala ito, walang makakakuwenta ng inaasahang value, at walang makakagaya ng payload kahit may kopya ito, kaya ang check ay dapat nasa server na tumatanggap ng mga request ng Meta para sa app. Hinihiling ng Meta na manatiling wala sa mga log at support request ang app secret, access token at client credentials. Ang sistemang tumatanggap ng mga event na ipinasa ng ibang app ay hindi talaga makakapag-check ng signature ng Meta, at umaasa na lang sa sarili nitong signature ng app na iyon.

Bakit kailangan ng bawat account ng sariling subscription?

Dahil itinatakda ng App Dashboard kung ano ang maaaring matanggap ng app, ngunit magsisimula lang ang notifications para sa isang account kapag naka-subscribe na rin ang account na iyon. Gamit ang Instagram Login, magpadala ng POST /<IG_ID>/subscribed_apps sa graph.instagram.com kasama ang Instagram User access token ng account at subscribed_fields na naglilista ng mga field na napili para sa app, na pinaghihiwalay ng kuwit. Kapag matagumpay ang tawag, ibinabalik nito ang success na naka-set sa 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 }

Ano ang ginagawa ng Meta kapag nabigo ang mga delivery?

Umuulit ito, pagkatapos ay sumusuko. Hinihiling ng gabay ng Meta ang 200 OK sa bawat notification at nagbababala na hindi ginagarantiya ang batching, hanggang 1,000 update. Ang update na nabigo ay agad na inuulit, pagkatapos ng ilan pang pag-ulit na may bumababang dalas sa loob ng 36 na oras, at tinatanggal pagkatapos nito, kaya posibleng dumating nang dalawang beses ang parehong event. Sumusunod ang mga messaging event sa mga patakaran ng Meta sa messaging delivery, na mas mabilis kumilos:

  • Inaasahan ang 200 OK sa loob ng 5 segundo, at ang nabigong delivery ay may ilang agarang retry, kaya i-deduplicate gamit ang mid ng mensahe.
  • Pagkatapos ng 15 minutong pagkabigo, may alert na ipapadala sa developer account.
  • Pagkatapos ng isang oras na pagkabigo, susunod ang alert na Webhooks Disabled, at ang app ay ina-unsubscribe sa webhooks ng account hanggang sa mag-subscribe itong muli.
  • Maaaring dumating nang wala sa ayos ang mga mensaheng ipinadala habang may pagkawala ng serbisyo, kaya ayusin ang mga ito ayon sa timestamp.

Ano ang dapat suriin kapag walang dumarating?

Ito ang checklist ng Meta sa troubleshooting, na sumasaklaw sa karamihan ng tahimik na endpoint, sa ganitong pagkakasunod:

  • Pumasa sa check ang callback URL, maaabot sa HTTPS na may valid na certificate; hindi suportado ang self-signed.
  • Napili ng app ang field at may access level na kailangan nito, ang Advanced Access para sa comments at live_comments.
  • Naka-enable ang notifications para sa account sa pamamagitan ng subscribed_apps, may token mula sa parehong login setup.
  • Natutugunan ng account ang mga patakaran ng field: kailangan ng comment notifications ng media na pag-aari ng pampublikong account.
  • Nagbabalik ang server ng success bago ito magsimula ng mabagal na trabaho.

Bakit muling nilalagdaan ng easyCoexistence ang mga ipinasa na event?

Dahil hindi maaaring ipasa ang signature ng Meta. Tumatanggap ang app ng easyCoexistence ng delivery ng Meta, sinusuri ang X-Hub-Signature-256 gamit ang sarili nitong app secret, agad na sumasagot sa Meta, at ipinapadala ang bawat entry para sa naka-connect na account sa endpoint na itinakda para sa account na iyon, sa loob ng bagong body na may platform, account_id, external_id at entry. Hindi ipinapasa ang header ng Meta at hindi ito mabe-verify kung wala ang secret na iyon, kaya bawat forward ay may Content-Type: application/json at X-EC-Signature, na may susi sa secret na pag-aari mismo ng account na iyon.

Paano i-verify ang X-EC-Signature?

Ang format ng header ay t=<unix>,v1=<hex>, kung saan ang v1 ay ang hex HMAC-SHA256 ng timestamp, isang tuldok, at ng raw body, na ginagamitan ng signing secret ng account. Kuwentahin muli ito sa mga byte na eksaktong natanggap, ikumpara sa constant time, at tanggihan ang timestamp na mas matanda sa 5 minuto.

  • Nagsisimula sa whsec_ ang secret at ipinapakita nang isang beses ng set_social_webhook_destination o ng PUT /channels/:id/webhook kapag itinakda ang URL.
  • Kapag muling itinakda ang URL, may bagong secret na ibinibigay, at ang null na URL ay nagpapatigil sa forwarding.
  • Bawat event ay ipinapadala nang isang beses, naghihintay nang hanggang 8 segundo, nang walang sinusundang redirect, sa HTTPS address na nareresolba sa public IP.
  • Ang pag-alis ng koneksyon ay nag-a-unsubscribe sa account mula sa webhooks ng Meta at nagbubura ng endpoint at secret nito.
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())

Mga karaniwang pagkakamali

  • Pagbabalik ng challenge bilang JSON o nakapaloob sa quotes. Inaasahan ng Meta ang mismong value ng hub.challenge bilang body, na may status na 200.
  • Pag-hash ng na-parse na body. Itinatapon ng JSON body parser ang eksaktong mga byte na pinirmahan ng Meta, kaya itago ang raw body para sa HMAC at i-parse ito pagkatapos.
  • Pag-subscribe sa app at pagkalimot sa account. Hangga't hindi nagtatagumpay ang POST /<IG_ID>/subscribed_apps para sa isang account, walang notifications na dumarating dito.
  • Pagpayag na mabigo ang endpoint nang isang oras. Dinidisable ng Meta ang messaging webhooks at ina-unsubscribe ang app sa account, na kailangang i-subscribe muli.
Ginagawa ito gamit ang EasyCoexistence

Ibukas ito sa set_social_webhook_destination o sa Partner API. US$ 9 hanggang US$ 0.75 kada koneksyon kada buwan, bumababa habang dumarami ang koneksyon, at may unang 3 araw na free trial.

Mga madalas itanong

Ano ang hub.challenge sa Instagram webhooks?

Isang integer na ipinapadala ng Meta sa verification GET nito. Pagkatapos suriin ang hub.verify_token, ibinabalik ito ng endpoint bilang response body, na nagpapatunay na kontrolado nito ang URL.

Bakit nawawala ang hub.mode at hub.challenge sa PHP?

Ginagawang underscore ng PHP ang mga tuldok sa pangalan ng parameter, kaya dumarating ang mga value ng verification ng Meta bilang hub_mode, hub_challenge at hub_verify_token.

Paano ko muling bubuksan ang Instagram webhooks pagkatapos i-disable ng Meta?

Ayusin muna ang endpoint, pagkatapos ay i-subscribe muli ang account gamit ang POST /<IG_ID>/subscribed_apps at ang parehong field.

Gumagana ba ang self-signed certificate para sa Instagram webhook endpoint?

Hindi. Hindi sinusuportahan ng Meta ang self-signed certificate: dapat maabot ang callback URL sa HTTPS na may valid na certificate, ang unang item sa checklist ng Meta sa troubleshooting.

Magpatuloy sa pagbabasa

I-connect ang inyong unang channel sa loob ng dalawang minuto.

Walang review ng platform na hihintayin. I-connect ang WhatsApp, Instagram, TikTok o iba pang channel, pagkatapos ay utusan ang inyong AI na mag-post, mag-reply o gumawa ng report, at panoorin itong gumana.

  • 3 araw na libre
  • Mag-cancel anumang oras
  • Official API lang
  • Minomonitor 24/7

Na-verify noong