Επαλήθευση webhook του Instagram: hub.challenge και X-Hub-Signature-256
Η ρύθμιση των webhooks του Instagram απαιτεί ένα endpoint HTTPS που απαντά στο αίτημα επαλήθευσης GET της Meta. Το αίτημα φέρει hub.mode με τιμή subscribe, hub.verify_token και hub.challenge, και το endpoint ελέγχει το token και επιστρέφει το challenge. Στη συνέχεια η Meta στέλνει με POST γεγονότα JSON, υπογεγραμμένα στο X-Hub-Signature-256 με το μυστικό κλειδί της εφαρμογής, μόλις η εφαρμογή εγγραφεί σε πεδία και κάθε λογαριασμός εγγραφεί μέσω του edge subscribed_apps.
Το easyCoexistence αναλαμβάνει την πλευρά της Meta: η εφαρμογή του περνά την επαλήθευση, ελέγχει το X-Hub-Signature-256, εγγράφει κάθε συνδεδεμένο λογαριασμό Instagram σε σχόλια, μηνύματα και αναφορές, και προωθεί τα γεγονότα στο HTTPS endpoint σας, υπογεγραμμένα με το X-EC-Signature και ένα κλειδί ανά λογαριασμό, παρακολουθώντας κάθε σύνδεση όλο το 24ωρο.
Η τιμή hub.mode υπάρχει πάντα στο αίτημα επαλήθευσης της Meta.
Το διάστημα κατά το οποίο η Meta επαναλαμβάνει μια αποτυχημένη ειδοποίηση, με μειούμενη συχνότητα, πριν την απορρίψει.
Αποτυχημένων παραδόσεων μηνυμάτων πριν η Meta στείλει ειδοποίηση στον λογαριασμό προγραμματιστή.
Των αποτυχουσών παραδόσεων μηνυμάτων πριν από την ειδοποίηση «Webhooks Disabled» και την απεγγραφή της εφαρμογής από τον λογαριασμό.
Η λειτουργία App mode που απαιτεί η Meta, πριν η εφαρμογή λάβει ειδοποιήσεις για τους λογαριασμούς των χρηστών της.
Πώς λειτουργεί η ρύθμιση των webhooks του Instagram;
Σε τέσσερα βήματα, με τη σειρά που τα δίνει ο οδηγός της Meta. Το endpoint πρέπει να περάσει την επαλήθευση πριν επιλεγεί οποιοδήποτε πεδίο, η εφαρμογή πρέπει να είναι Live για να λαμβάνει ειδοποιήσεις για τους λογαριασμούς των χρηστών της, και για την πρόσβαση παραγωγής απαιτείται επαλήθευση της επιχείρησης.
Τι περιέχει το αίτημα επαλήθευσης;
Ένα GET προς το callback URL, που στέλνεται κάθε φορά που ρυθμίζεται το προϊόν Webhooks στο App Dashboard. Όταν το hub.verify_token ταιριάζει με το δικό του token του endpoint, η απάντηση είναι 200 με την τιμή hub.challenge ως ολόκληρο το σώμα· διαφορετικά, 403. Το dashboard αναφέρει αν το endpoint πέρασε την επαλήθευση.
- hub.mode: πάντα subscribe.
- hub.challenge: ένας ακέραιος που δημιουργεί η Meta και το endpoint πρέπει να τον στείλει πίσω.
- hub.
verify_token: η συμβολοσειρά που εισάγεται στο πεδίο Verify Token του dashboard, την οποία πρέπει να γνωρίζουν μόνο η Meta και το endpoint. - Στην PHP, οι τελείες στα ονόματα αυτά γίνονται κάτω παύλες, οπότε οι τιμές φτάνουν ως
hub_mode,hub_challengeκαιhub_verify_token.
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 και τα πεδία;
Στο 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, και το Manage σάς επιτρέπει να απεγγραφείτε από οποιοδήποτε από αυτά. Το κουμπί Test στέλνει δοκιμαστική ειδοποίηση για επιλεγμένο πεδίο.
Πώς ελέγχεται το X-Hub-Signature-256;
Η Meta υπογράφει κάθε ειδοποίηση γεγονότος με HMAC-SHA256 του payload, με κλειδί το μυστικό κλειδί της εφαρμογής, και την στέλνει στην κεφαλίδα X-Hub-Signature-256 ως sha256= ακολουθούμενο από το δεκαεξαδικό digest. Ο παραλήπτης υπολογίζει το ίδιο HMAC πάνω στο ακατέργαστο σώμα του αιτήματος και το συγκρίνει με την κεφαλίδα σε σταθερό χρόνο. Ο οδηγός μηνυμάτων της Meta σημειώνει ότι η υπογραφή καλύπτει το payload με τα Unicode διαφυγμένα, οπότε ο κατακερματισμός αποκωδικοποιημένου ή ξανά σειριοποιημένου JSON δίνει διαφορετικό αποτέλεσμα.
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);Γιατί μόνο το μυστικό κλειδί της εφαρμογής μπορεί να την ελέγξει;
Επειδή η υπογραφή είναι HMAC με κλειδί αυτό το μυστικό. Χωρίς αυτό, κανείς δεν μπορεί να υπολογίσει την αναμενόμενη τιμή, και όποιος κατέχει αντίγραφο ενός payload δεν μπορεί να φτιάξει έγκυρο. Ο έλεγχος ανήκει επομένως στον διακομιστή που λαμβάνει τα αιτήματα της Meta για την εφαρμογή. Η Meta ζητά τα μυστικά κλειδιά των εφαρμογών, τα access tokens και τα client credentials να μένουν εκτός καταγραφών και αιτημάτων υποστήριξης. Ένα σύστημα που λαμβάνει γεγονότα που μεταβιβάζει άλλη εφαρμογή δεν μπορεί καθόλου να ελέγξει την υπογραφή της Meta και βασίζεται στη δική της υπογραφή της άλλης εφαρμογής.
Γιατί κάθε λογαριασμός χρειάζεται δική του εγγραφή;
Επειδή το App Dashboard ορίζει τι μπορεί να λάβει η εφαρμογή, και οι ειδοποιήσεις για έναν λογαριασμό ξεκινούν μόνο όταν και αυτός ο λογαριασμός είναι εγγεγραμμένος. Με το Instagram Login, στείλτε POST /<IG_ID>/subscribed_apps στο graph.instagram.com με το Instagram User access token του λογαριασμού και το subscribed_fields που περιέχει τα πεδία που επιλέξατε για την εφαρμογή, χωρισμένα με κόμματα. Μια επιτυχής κλήση επιστρέφει success ίσο με true.
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 για κάθε ειδοποίηση και προειδοποιεί ότι η ομαδοποίηση, έως 1.000 ενημερώσεις, δεν είναι εγγυημένη. Μια αποτυχημένη ενημέρωση επαναλαμβάνεται αμέσως, και στη συνέχεια λίγες ακόμη φορές με μειούμενη συχνότητα σε διάστημα 36 ωρών, και μετά απορρίπτεται, οπότε το ίδιο γεγονός μπορεί να φτάσει δύο φορές. Τα γεγονότα μηνυμάτων ακολουθούν τους κανόνες παράδοσης μηνυμάτων της Meta, που δρουν γρηγορότερα:
- Αναμένεται 200 OK εντός 5 δευτερολέπτων, και μια αποτυχημένη παράδοση λαμβάνει λίγες άμεσες επαναλήψεις· γι' αυτό αφαιρέστε τα διπλότυπα βάσει του mid του μηνύματος.
- Μετά από 15 λεπτά αποτυχιών, στέλνεται ειδοποίηση στον λογαριασμό προγραμματιστή.
- Μετά από μία ώρα αποτυχιών, ακολουθεί η ειδοποίηση «Webhooks Disabled», και η εφαρμογή απεγγράφεται από τα webhooks του λογαριασμού μέχρι να εγγραφεί ξανά.
- Τα μηνύματα που στάλθηκαν κατά τη διάρκεια διακοπής μπορεί να φτάσουν εκτός σειράς, οπότε ταξινομήστε τα κατά χρονική σήμανση.
Τι πρέπει να ελέγξετε όταν δεν φτάνει τίποτα;
Η λίστα ελέγχου αντιμετώπισης προβλημάτων της Meta, που καλύπτει τα περισσότερα σιωπηλά endpoints, με αυτή τη σειρά:
- Το callback URL πέρασε τον έλεγχο και είναι προσβάσιμο μέσω HTTPS με έγκυρο πιστοποιητικό· τα αυτο-υπογεγραμμένα δεν υποστηρίζονται.
- Η εφαρμογή επέλεξε το πεδίο και έχει το επίπεδο πρόσβασης που χρειάζεται, Advanced Access για comments και
live_comments. - Οι ειδοποιήσεις είναι ενεργοποιημένες για τον λογαριασμό μέσω του
subscribed_apps, με token από την ίδια ρύθμιση σύνδεσης. - Ο λογαριασμός πληροί τους κανόνες του πεδίου: οι ειδοποιήσεις σχολίων χρειάζονται media που ανήκουν σε δημόσιο λογαριασμό.
- Ο server επιστρέφει success πριν ξεκινήσει αργές εργασίες.
Γιατί το easyCoexistence υπογράφει ξανά τα προωθημένα γεγονότα;
Επειδή η υπογραφή της Meta δεν μπορεί να ταξιδέψει. Η εφαρμογή του easyCoexistence λαμβάνει την παράδοση της Meta, ελέγχει το X-Hub-Signature-256 με το δικό της μυστικό κλειδί εφαρμογής, απαντά στη Meta αμέσως και στέλνει με POST κάθε εγγραφή για συνδεδεμένο λογαριασμό στο endpoint που ορίζεται για τον λογαριασμό αυτό, μέσα σε νέο σώμα με τα πεδία platform, account_id, external_id και entry. Η κεφαλίδα της Meta δεν προωθείται και δεν θα μπορούσε να ελεγχθεί χωρίς εκείνο το κλειδί· γι' αυτό κάθε προώθηση φέρει Content-Type: application/json και X-EC-Signature, υπογεγραμμένο με κλειδί που ανήκει σε αυτόν ακριβώς τον λογαριασμό.
Πώς ελέγχετε το X-EC-Signature;
Η κεφαλίδα έχει τη μορφή t=<unix>,v1=<hex>, όπου το v1 είναι το δεκαεξαδικό HMAC-SHA256 της χρονικής σήμανσης, μιας τελείας και του ακατέργαστου σώματος, με κλειδί το κλειδί υπογραφής του λογαριασμού. Υπολογίστε το ξανά πάνω στα bytes ακριβώς όπως ελήφθησαν, συγκρίνετε σε σταθερό χρόνο, και απορρίψτε χρονική σήμανση παλαιότερη των 5 λεπτών.
- Το κλειδί αρχίζει με whsec_ και εμφανίζεται μία φορά, από το
set_social_webhook_destinationή το PUT /channels/:id/webhook όταν οριστεί το URL. - Όταν ορίζετε ξανά το URL, εκδίδεται νέο κλειδί, και ένα null URL απενεργοποιεί την προώθηση.
- Κάθε γεγονός στέλνεται μία φορά, με αναμονή έως 8 δευτερολέπτων, χωρίς ακολούθηση ανακατευθύνσεων, σε διεύθυνση HTTPS που επιλύεται σε δημόσια IP.
- Η αφαίρεση της σύνδεσης απεγγράφει τον λογαριασμό από τα webhooks της Meta και καθαρίζει το endpoint και το κλειδί του.
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 αυτή καθαυτή ως σώμα, με κατάσταση 200.
- Η κατακερματοποίηση ενός αναλυμένου σώματος. Ο αναλυτής JSON πετάει τα ακριβή bytes που υπέγραψε η Meta, οπότε κρατήστε το ακατέργαστο σώμα για το HMAC και αναλύστε το μετά.
- Η εγγραφή της εφαρμογής χωρίς τον λογαριασμό. Μέχρι να πετύχει το POST /<IG_ID>/subscribed_apps για έναν λογαριασμό, δεν φτάνει καμία ειδοποίηση γι' αυτόν.
- Το να αφήνετε ένα endpoint να αποτυγχάνει για μία ώρα. Η Meta απενεργοποιεί τα webhooks μηνυμάτων και απεγγράφει την εφαρμογή από τον λογαριασμό, ο οποίος πρέπει έπειτα να εγγραφεί ξανά.
Ενεργοποιήστε το με το set_social_webhook_destination ή το Partner API. Από US$ 9 έως US$ 0,75 ανά σύνδεση τον μήνα, με μείωση όσο προσθέτετε συνδέσεις, με τις πρώτες 3 ημέρες δωρεάν.
Συχνές ερωτήσεις
Τι είναι το hub.challenge στα webhooks του Instagram;
Ένας ακέραιος που στέλνει η Meta στο αίτημα GET επαλήθευσης. Αφού ελέγξει το hub.verify_token, το endpoint τον επιστρέφει ως σώμα απάντησης, κάτι που αποδεικνύει ότι ελέγχει το URL.
Γιατί λείπουν τα hub.mode και hub.challenge στην PHP;
Η PHP μετατρέπει τις τελείες στα ονόματα παραμέτρων σε κάτω παύλες, οπότε οι τιμές επαλήθευσης της Meta φτάνουν ως hub_mode, hub_challenge και hub_verify_token.
Πώς μπορώ να ενεργοποιήσω ξανά τα webhooks του Instagram αφού τα απενεργοποιήσει η Meta;
Διορθώστε το endpoint και έπειτα εγγράψτε ξανά τον λογαριασμό με POST /<IG_ID>/subscribed_apps και τα ίδια πεδία.
Λειτουργεί ένα αυτο-υπογεγραμμένο πιστοποιητικό για endpoint webhook του Instagram;
Όχι, η Meta δεν υποστηρίζει αυτο-υπογεγραμμένα πιστοποιητικά: το callback URL πρέπει να είναι προσβάσιμο μέσω HTTPS με έγκυρο πιστοποιητικό, το πρώτο στοιχείο της λίστας ελέγχου της Meta.
Συνεχίστε την ανάγνωση
Συνδέστε το πρώτο σας κανάλι σε δύο λεπτά.
Χωρίς αναμονή για έλεγχο από τις πλατφόρμες. Συνδέστε WhatsApp, Instagram, TikTok ή άλλο κανάλι, ζητήστε από το AI σας να δημοσιεύσει, να απαντήσει ή να δημιουργήσει αναφορά και δείτε το να δουλεύει.
- 3 ημέρες δωρεάν
- Ακύρωση ανά πάσα στιγμή
- Μόνο επίσημα API
- Παρακολούθηση 24/7
Επαληθεύτηκε στις