ΣύνδεσηΞεκινήστε δωρεάν δοκιμή
easyCoexistence Επίσημα API

Επαλήθευση του webhook του Facebook: hub.challenge και X-Hub-Signature-256

Το Facebook επαληθεύει ένα endpoint webhook με ένα GET που φέρει το hub.mode με τιμή subscribe, το hub.verify_token και το hub.challenge. Το endpoint ελέγχει το token έναντι αυτού που έχει οριστεί στο App Dashboard και επιστρέφει το challenge ως σώμα. Κάθε συμβάν φτάνει έπειτα ως POST υπογεγραμμένο στο X-Hub-Signature-256: sha256= ακολουθούμενο από το HMAC-SHA256 του payload, με κλειδί το App Secret.

Το easyCoexistence αναλαμβάνει το μέρος της Meta για κάθε Σελίδα που συνδέετε.

subscribe

Η τιμή που έχει πάντα το hub.mode στο αίτημα επαλήθευσης της Meta· το hub.challenge είναι ακέραιος αριθμός που πρέπει να επιστραφεί.

sha256=

Πρόθεμα του X-Hub-Signature-256, ακολουθούμενο από την υπογραφή SHA256 που δημιουργεί η Meta από το payload και το App Secret.

5 seconds

Πόσο γρήγορα πρέπει ένα endpoint webhook του Messenger να απαντά σε κάθε κοινοποίηση με 200 OK.

1 hour

Ο αριθμός των αποτυχημένων παραδόσεων πριν από μια ειδοποίηση «Webhooks Disabled» και την απεγγραφή της εφαρμογής από τη Σελίδα.

36 hours

Για πόση ώρα η Meta επαναλαμβάνει μια αποτυχημένη κοινοποίηση Σελίδας, με μειούμενη συχνότητα, πριν την απορρίψει.

Τι περιέχει το αίτημα επαλήθευσης της Meta;

Ένα GET προς το callback URL, που αποστέλλεται όποτε ρυθμίζεται το προϊόν Webhooks στο App Dashboard ή δημιουργείται εγγραφή μέσω του /{app-id}/subscriptions. Συνοδεύεται από τρεις παραμέτρους ερωτήματος:

  • hub.mode: πάντα subscribe.
  • hub.challenge: ακέραιος αριθμός που πρέπει να επιστρέψει το endpoint.
  • hub.verify_token: η συμβολοσειρά που έχει καταχωρηθεί στο πεδίο Verify Token του dashboard.
  • Η PHP μετατρέπει τις τελείες σε κάτω παύλες, οπότε τις διαβάζει ως hub_mode, hub_challenge και hub_verify_token.

Πώς πρέπει να απαντά το endpoint;

Με 200, του οποίου το σώμα είναι αποκλειστικά η τιμή του hub.challenge, μόνο όταν το hub.mode είναι subscribe και το hub.verify_token ταιριάζει. Σε κάθε άλλη περίπτωση επιστρέφεται 403, όπως στην εφαρμογή δείγματος της Meta. Το dashboard δείχνει αν το endpoint πέρασε τον έλεγχο, και το /{app-id}/subscriptions απαντά με επιτυχία ή σφάλμα. Το endpoint χρειάζεται HTTPS με έγκυρο πιστοποιητικό TLS ή SSL, αφού τα αυτοϋπογεγραμμένα πιστοποιητικά δεν υποστηρίζονται.

Πώς υπολογίζεται το X-Hub-Signature-256;

Ως HMAC-SHA256 του payload του αιτήματος, με κλειδί το App Secret της εφαρμογής, γραμμένο σε πεζά hex μετά το sha256=. Ο οδηγός Messenger της Meta προσθέτει ότι η υπογραφή καλύπτει το payload με Unicode σε escape, οπότε μια συμβολοσειρά όπως äöå μετράει ως \u00e4\u00f6\u00e5. Κατακερματίστε το ακατέργαστο σώμα ακριβώς όπως λήφθηκε, ποτέ ένα αποκωδικοποιημένο ή ξανασειριοποιημένο αντίγραφο. Η Meta λέει ότι η επικύρωση είναι προαιρετική, αλλά την συνιστά ανεπιφύλακτα.

Πώς ελέγχεται στον κώδικα;

Κρατήστε τα ακατέργαστα bytes, υπολογίστε το HMAC, συγκρίνετε σε σταθερό χρόνο και μετά αναλύστε. Η get_data του Flask επιστρέφει το σώμα αμετάβλητο, και αυτό ακριβώς υπολογίστηκε η υπογραφή· η ανάλυση και η ξανασειριοποίηση θα άλλαζαν τα bytes. Ένα μικρό endpoint που απαντά στην επαλήθευση και ελέγχει κάθε 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 μετά την επαλήθευση;

Ένα 200 OK για κάθε κοινοποίηση, εντός 5 δευτερολέπτων για συμβάντα Messenger. Η Meta ομαδοποιεί έως 1.000 ενημερώσεις ανά παράδοση χωρίς να το εγγυάται, και χειρίζεται τις αποτυχίες ως εξής:

  • Κοινοποιήσεις Σελίδας: επαναλαμβάνονται αμέσως, έπειτα λίγες φορές ακόμη με μειούμενη συχνότητα σε διάστημα 36 ωρών, και τελικά απορρίπτονται.
  • Κοινοποιήσεις Messenger: επαναλαμβάνονται λίγες φορές αμέσως. Μετά από 15 λεπτά αποτυχιών, μια ειδοποίηση φτάνει στον λογαριασμό προγραμματιστή.
  • Μετά από μία ώρα αποτυχιών ακολουθεί ειδοποίηση «Webhooks Disabled», και η εφαρμογή απεγγράφεται από τη Σελίδα μέχρι να εγγραφεί ξανά.
  • Οι επαναλήψεις μπορούν να παραδώσουν ένα συμβάν δύο φορές και εκτός σειράς. Γι' αυτό αφαιρέστε τα διπλότυπα και ταξινομήστε τα μηνύματα κατά τη χρονική τους σήμανση.
  • Παλαιότερες κοινοποιήσεις δεν μπορούν να ερωτηθούν αργότερα. Γι' αυτό αποθηκεύστε ό,τι χρειάζεστε καθώς φτάνει.

Πώς το easyCoexistence περνά τους ελέγχους της Meta;

Η εφαρμογή της στη Meta έχει ένα callback URL για τις Σελίδες που συνδέει, και αυτό το endpoint κάνει μόνο του και τους δύο ελέγχους. Απαντά στο GET μόνο όταν το hub.mode είναι subscribe και το hub.verify_token ταιριάζει, με σύγκριση σε σταθερό χρόνο, και επιστρέφει 403 διαφορετικά. Διαβάζει κάθε POST ως ακατέργαστο κείμενο, υπολογίζει ξανά το X-Hub-Signature-256 με το App Secret του, απορρίπτει με 401 μια ασυμφωνία και απαντά στη Meta αμέσως, χειριζόμενο το συμβάν μετά την απάντηση.

Πώς υπογράφει το easyCoexistence όσα προωθεί;

Με δική του υπογραφή, αφού η κεφαλίδα της Meta μπορεί να ελεγχθεί μόνο με το App Secret του easyCoexistence και δεν προωθείται. Κάθε καταχώρηση για Σελίδα με ορισμένο endpoint αποστέλλεται ως POST σε μορφή JSON, {platform, account_id, external_id, entry}, με κεφαλίδα X-EC-Signature της μορφής t=<unix>,v1=<hex>. Το v1 είναι το HMAC-SHA256 της χρονικής σήμανσης, μιας τελείας και του ακατέργαστου σώματος, με κλειδί το signing secret εκείνης της Σελίδας:

  • Το μυστικό ξεκινά με whsec_ και εμφανίζεται μία φορά, από το set_social_webhook_destination ή το PUT /channels/:id/webhook του Partner API.
  • Αν ξαναοριστεί το URL, εκδίδεται νέο μυστικό· ένα null URL απενεργοποιεί την προώθηση.
  • Κάθε προώθηση στέλνεται μία φορά, με αναμονή έως 8 δευτερόλεπτα, χωρίς ακολούθηση ανακατευθύνσεων, σε διεύθυνση HTTPS που αντιστοιχεί σε δημόσια IP.
  • Δεν κρατείται αντίγραφο του συμβάντος, οπότε δεν υπάρχει από πού να γίνει επανάληψη.

Πώς επαληθεύετε το X-EC-Signature;

Χωρίστε την κεφαλίδα σε t και v1, απορρίψτε χρονική σήμανση παλαιότερη από 5 λεπτά, υπολογίστε ξανά το HMAC πάνω στο t, μια τελεία και το ακατέργαστο σώμα με το signing secret της Σελίδας, και συγκρίνετε σε σταθερό χρόνο. Στο Node.js, με το σώμα κρατημένο ως ακατέργαστα bytes:

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

Συνηθισμένα λάθη

  • Τυλίγετε το hub.challenge σε JSON ή εισαγωγικά. Το σώμα της απάντησης 200 πρέπει να είναι η ίδια η τιμή του challenge.
  • Υπολογίζετε το HMAC μετά από έναν JSON parser. Η ανάλυση και η ξανασειριοποίηση αλλάζουν τα bytes, και η Meta υπογράφει το payload με Unicode σε escape, οπότε κατακερματίστε το ακατέργαστο σώμα.
  • Κάνετε τη δουλειά πριν απαντήσετε. Το Messenger περιμένει 200 μέσα σε 5 δευτερόλεπτα, και μία ώρα αποτυχιών απεγγράφει την εφαρμογή από τη Σελίδα.
  • Ελέγχετε την υπογραφή της Meta σε προωθημένα συμβάντα. Η Meta υπογράφει με το App Secret του easyCoexistence· ένα προωθημένο συμβάν φέρει X-EC-Signature, που ελέγχεται με το signing secret της Σελίδας.
Κάντε το με EasyCoexistence

Η εφαρμογή του απαντά στο hub.challenge, ελέγχει το X-Hub-Signature-256 και εγγράφει τη Σελίδα στα feed, τα μηνύματα και τα mention. Έπειτα προωθεί τα συμβάντα στο δικό σας endpoint HTTPS, υπογεγραμμένα με X-EC-Signature και με μυστικό για εκείνη τη Σελίδα. Από US$ 9 έως US$ 0.75 ανά σύνδεση τον μήνα, με μείωση όσο προσθέτετε συνδέσεις, και με τις πρώτες 3 ημέρες δωρεάν.

Συχνές ερωτήσεις

Από πού προέρχεται το verify_token;

Το επιλέγετε εσείς. Είναι η συμβολοσειρά που καταχωρείτε στο πεδίο Verify Token κατά τη ρύθμιση των webhooks στο App Dashboard, ή το verify_token που στέλνετε στο /{app-id}/subscriptions.

Μπορώ να δοκιμάσω την επαλήθευση με curl;

Ναι. Ο οδηγός Messenger της Meta στέλνει ένα GET με hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED και hub.mode=subscribe, και ένα λειτουργικό endpoint απαντά CHALLENGE_ACCEPTED.

Τι γίνεται αν το endpoint αποτυγχάνει για μία ώρα;

Η Meta στέλνει ειδοποίηση «Webhooks Disabled» και απεγγράφει την εφαρμογή από τη Σελίδα. Αφού διορθώσετε το endpoint, εγγράψτε ξανά τη Σελίδα μέσω του subscribed_apps.

Χρειάζομαι δική μου εφαρμογή Meta για να λαμβάνω τα webhooks μιας Σελίδας;

Όχι με το easyCoexistence. Η Meta παραδίδει στη δική του εφαρμογή, που προωθεί τα συμβάντα κάθε Σελίδας στο endpoint που ορίζετε, υπογεγραμμένα με X-EC-Signature.

Συνεχίστε την ανάγνωση

Εγγραφή μιας Σελίδας Facebook στα webhooks: το edge subscribed_appsΠώς το POST /{page-id}/subscribed_apps εγγράφει μια Σελίδα Facebook σε πεδία webhook: tokens, εργασίες, εγγραφή εφαρμογής, έλεγχος, αφαίρεση.Πεδία webhook της Facebook Page: η πλήρης λίσταΤα 64 πεδία webhook της Facebook Page της Meta: feed, mention, πεδία Messenger όπως τα messages, πεδία προφίλ και το δικαίωμα του καθενός.Το webhook του Messenger για Σελίδες Facebook: μηνύματα και συμβάντα μνείαςΤα πεδία του webhook της Σελίδας Facebook για μηνύματα και μνείες: σχήμα payload, ID αποστολέων, συνημμένα και πώς φτάνουν τα συμβάντα στο endpoint σας.Webhook του feed σελίδας Facebook: σχόλια, αναρτήσεις και αντιδράσειςΤι στέλνει το webhook του feed σελίδας Facebook για σχόλια, αναρτήσεις και αντιδράσεις, με τα πεδία item και verb και τη μορφή του payload της Meta.Token πρόσβασης σελίδας Facebook: πόσο διαρκεί και τι το ακυρώνειΠώς αποκτάται token πρόσβασης σελίδας Facebook χωρίς ημερομηνία λήξης, ποιος μπορεί να το αποκτήσει και τι κάνει τη Meta να σταματήσει να το δέχεται.

Συνδέστε το πρώτο σας κανάλι σε δύο λεπτά.

Χωρίς αναμονή για έλεγχο από τις πλατφόρμες. Συνδέστε WhatsApp, Instagram, TikTok ή άλλο κανάλι, ζητήστε από το AI σας να δημοσιεύσει, να απαντήσει ή να δημιουργήσει αναφορά και δείτε το να δουλεύει.

  • 3 ημέρες δωρεάν
  • Ακύρωση ανά πάσα στιγμή
  • Μόνο επίσημα API
  • Παρακολούθηση 24/7

Επαληθεύτηκε στις