Kirjaudu sisäänAloita ilmainen kokeilu
easyCoexistence Viralliset API:t

Facebook-webhookin vahvistus: hub.challenge ja X-Hub-Signature-256

Facebook vahvistaa webhook-päätepisteen GET-pyynnöllä, jossa ovat hub.mode-arvo subscribe, hub.verify_token ja hub.challenge. Päätepiste vertaa tokenia sovelluksen hallintapaneelissa annettuun tokeniin ja palauttaa hub.challenge-arvon vastauksen rungossa. Jokainen tapahtuma saapuu POST-pyyntönä, jonka X-Hub-Signature-256 on muotoa sha256= ja sitä seuraa payloadin HMAC-SHA256, avaimena sovelluksen salaisuus.

easyCoexistence hoitaa Metan puolen jokaiselle yhdistämällesi Facebook-sivulle: sen sovellus vastaa hub.challenge-vahvistukseen, tarkistaa X-Hub-Signature-256:n ja tilaa sivun syötteeseen, viesteihin ja maininnoihin.

subscribe

Metan vahvistuspyynnössä hub.mode on aina subscribe. hub.challenge on kokonaisluku, joka palautetaan takaisin.

sha256=

X-Hub-Signature-256:n etuliite, jonka perässä on SHA256-allekirjoitus. Meta muodostaa sen payloadista ja App Secretista.

5 seconds

Kuinka nopeasti Messenger-webhookin päätepisteen tulee vastata jokaiseen ilmoitukseen 200 OK:lla.

1 hour

Epäonnistuneiden toimitusten määrä, jonka jälkeen tulee Webhooks Disabled -hälytys ja sovellus peruutetaan Facebook-sivun tilauksesta.

36 hours

Kuinka kauan Meta yrittää uudelleen epäonnistunutta Facebook-sivun ilmoitusta harvenevin välein ennen kuin se hylätään.

Mitä Metan vahvistuspyyntö sisältää?

GET-pyyntö takaisinkutsu-URL-osoitteeseen. Meta lähettää sen aina, kun Webhooks-tuote määritetään sovelluksen hallintapaneelissa tai tilaus luodaan kutsulla /{app-id}/subscriptions. Pyynnön mukana tulee kolme kyselyparametria:

  • hub.mode: aina subscribe.
  • hub.challenge: kokonaisluku, jonka päätepisteen on palautettava.
  • hub.verify_token: merkkijono, joka syötetään hallintapaneelin Verify Token -kenttään.
  • PHP muuntaa pisteet alaviivoiksi, joten se lukee ne muodossa hub_mode, hub_challenge ja hub_verify_token.

Miten päätepisteen tulee vastata siihen?

200-vastauksella, jonka koko runko on hub.challenge-arvo, mutta vain kun hub.mode on subscribe ja hub.verify_token täsmää. Muussa tapauksessa vastataan 403:lla, kuten Metan esimerkkisovelluksessa. Hallintapaneeli kertoo, läpäisikö päätepiste tarkistuksen, ja /{app-id}/subscriptions vastaa onnistumisella tai virheellä. Päätepisteen on käytettävä HTTPS:ää, jolla on voimassa oleva TLS- tai SSL-sertifikaatti, sillä itse allekirjoitettuja sertifikaatteja ei tueta.

Miten X-Hub-Signature-256 lasketaan?

HMAC-SHA256-tiivisteenä pyynnön payloadista, avaimena sovelluksen App Secret, kirjoitettuna pienillä heksadesimaalimerkeillä sha256=-etuliitteen jälkeen. Metan Messenger-ohje lisää, että allekirjoitus kattaa payloadin unicode-escapattuna, joten merkkijono kuten äöå lasketaan muotoon \u00e4\u00f6\u00e5: tiivistä raaka runko täsmälleen sellaisena kuin se saapui, älä koskaan dekoodattua tai uudelleen sarjoitettua kopiota. Meta sanoo validoinnin olevan vapaaehtoista, mutta suosittelee sitä vahvasti.

Miten allekirjoitus tarkistetaan koodissa?

Säilytä raakatavut, laske HMAC, vertaa vakioajassa ja jäsennä vasta sitten. Flaskin get_data palauttaa rungon koskemattomana, eli juuri sen, jonka yli allekirjoitus laskettiin. Jos runko jäsennettäisiin ensin ja sarjoitettaisiin uudelleen, tavut muuttuisivat. Pieni päätepiste, joka vastaa vahvistukseen ja tarkistaa jokaisen POST-pyynnön:

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

Mitä Meta odottaa vahvistuksen jälkeen?

200 OK jokaiselle ilmoitukselle, Messenger-tapahtumille 5 sekunnin sisällä. Meta yhdistää enintään 1 000 päivitystä yhteen toimitukseen, mutta ei takaa sitä. Virhetilanteet käsitellään näin:

  • Facebook-sivun ilmoitukset: yritetään heti uudelleen, sitten muutaman kerran harvenevin välein 36 tunnin ajan, ja lopuksi hylätään.
  • Messenger-ilmoitukset: yritetään muutaman kerran heti. 15 minuutin virheiden jälkeen kehittäjän tilille lähetetään hälytys.
  • Tunnin virheiden jälkeen lähetetään Webhooks Disabled -hälytys, ja sovellus peruutetaan Facebook-sivun tilauksesta, kunnes se tilaa sen uudelleen.
  • Uudelleenyritykset voivat toimittaa tapahtuman kahdesti ja väärässä järjestyksessä, joten poista kaksoiskappaleet ja lajittele viestit aikaleiman mukaan.
  • Aiempia ilmoituksia ei voi kysyä jälkikäteen, joten tallenna tarvitsemasi tiedot heti, kun ne saapuvat.

Miten easyCoexistence läpäisee Metan tarkistukset?

Sen Meta-sovelluksessa on yksi takaisinkutsu-URL-osoite yhdistämilleen Facebook-sivuille, ja tämä päätepiste tekee molemmat tarkistukset itse. Se vastaa GET-pyyntöön vain, kun hub.mode on subscribe ja hub.verify_token täsmää (vertailu vakioajassa), muuten 403. Se lukee jokaisen POST-pyynnön raakatekstinä, laskee X-Hub-Signature-256:n uudelleen sovelluksen salaisuudella, hylkää epäsopivuuden 401:llä ja vastaa Metalle heti, käsitellen tapahtuman vastauksen jälkeen.

Miten easyCoexistence allekirjoittaa välittämänsä tapahtumat?

Omalla allekirjoituksellaan, koska Metan otsaketta voi tarkistaa vain easyCoexistencen App Secretilla eikä sitä välitetä eteenpäin. Jokainen yhdistetyn Facebook-sivun merkintä, jolle on asetettu päätepiste, lähetetään sinne POST-pyyntönä JSON-muodossa {platform, account_id, external_id, entry}. Mukana on X-EC-Signature-otsake muodossa t=<unix>,v1=<hex>. Tässä v1 on HMAC-SHA256 aikaleimasta, pisteestä ja raakarungosta, avaimena kyseisen sivun allekirjoitussalaisuus:

  • Salaisuus alkaa etuliitteellä whsec_ ja näytetään kerran, set_social_webhook_destination-kutsulla tai Partner API:n PUT /channels/:id/webhook -pyynnöllä.
  • URL:n asettaminen uudelleen luo uuden salaisuuden, ja null-URL lopettaa välittämisen.
  • Jokainen välitys lähetetään kerran, odottaen enintään 8 sekuntia, ilman uudelleenohjauksien seuraamista, HTTPS-osoitteeseen, joka ratkeaa julkiseen IP-osoitteeseen.
  • Tapahtumasta ei säilytetä kopiota, joten sitä ei voi yrittää uudelleen.

Miten X-EC-Signature tarkistetaan?

Jaa otsake osiin t ja v1, hylkää aikaleima, joka on yli 5 minuuttia vanha, ja laske HMAC uudelleen merkkijonosta, jossa on t, piste ja raakarunko, sivun allekirjoitussalaisuudella. Vertaa tulos vakioajassa. Node.js:ssä, kun runko säilytetään raakatavuina:

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

Yleiset virheet

  • hub.challenge-arvon kääriminen JSON-muotoon tai lainausmerkkeihin. 200-vastauksen rungon on oltava itse hub.challenge-arvo.
  • HMAC:n laskeminen JSON-jäsentimen jälkeen. Jäsentäminen ja uudelleensarjoittaminen muuttaa tavut, ja Meta allekirjoittaa payloadin unicode-escapattuna, joten tiivistä raaka runko.
  • Työn tekeminen ennen vastaamista. Messenger odottaa 200-vastausta 5 sekunnin kuluessa, ja tunnin virheet peruuttavat sovelluksen tilauksen Facebook-sivulta.
  • Metan allekirjoituksen tarkistaminen välitetyissä tapahtumissa. Meta allekirjoittaa easyCoexistencen App Secretilla. Välitetyssä tapahtumassa on X-EC-Signature, jota tarkistetaan Facebook-sivun allekirjoitussalaisuudella.
Näin teet tämän EasyCoexistencen avulla

Tapahtumat välitetään HTTPS-päätepisteeseesi allekirjoitettuina X-EC-Signature-otsakkeella, jonka salaisuus on kyseiselle sivulle. Hinta on US$ 9 per yhteys kuukaudessa ja laskee US$ 0,75:een, kun yhteyksiä lisätään. Ensimmäiset 3 päivää ovat ilmaista kokeilua.

Usein kysytyt kysymykset

Mistä vahvistustoken tulee?

Valitset sen itse. Se on merkkijono, joka syötetään Verify Token -kenttään sovelluksen hallintapaneelissa webhookeja määritettäessä, tai verify_token, joka lähetetään kutsulla /{app-id}/subscriptions.

Voinko testata vahvistuksen curlilla?

Kyllä. Metan Messenger-ohje lähettää GET-pyynnön, jossa ovat hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED ja hub.mode=subscribe. Toimiva päätepiste vastaa CHALLENGE_ACCEPTED.

Mitä tapahtuu, jos päätepisteeni epäonnistuu tunnin ajan?

Meta lähettää Webhooks Disabled -hälytyksen ja peruuttaa sovelluksen tilauksen Facebook-sivulta. Kun päätepiste on korjattu, tilaa sivu uudelleen subscribed_apps-kutsulla.

Tarvitsenko oman Meta-sovelluksen Facebook-sivun webhookien vastaanottamiseen?

Et easyCoexistencen kanssa. Meta toimittaa tapahtumat omaan sovellukseensa, joka välittää jokaisen Facebook-sivun tapahtumat asettamallesi päätepisteelle allekirjoitettuina X-EC-Signature-otsakkeella.

Lue lisää

Yhdistä ensimmäinen kanavasi kahdessa minuutissa.

Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.

  • 3 päivää ilmaiseksi
  • Peruuta milloin tahansa
  • Vain viralliset API:t
  • Valvottu 24/7

Vahvistettu