Giriş yapınÜcretsiz denemeyi başlatın
easyCoexistence Resmi API'ler

Facebook webhook doğrulaması: hub.challenge ve X-Hub-Signature-256

Facebook bir webhook uç noktasını, hub.mode değeri subscribe olan, hub.verify_token ve hub.challenge içeren bir GET isteğiyle doğrular. Uç nokta, token'ı App Dashboard'daki değerle karşılaştırır ve challenge değerini gövde olarak döndürür. Her olay bunun ardından, X-Hub-Signature-256 başlığında imzalanmış bir POST olarak gelir: sha256= ön ekini, uygulama sırrıyla anahtarlanmış payload'un HMAC-SHA256 değeri izler.

easyCoexistence, bağladığınız her Page için Meta tarafını yönetir: uygulaması hub.challenge değerine yanıt verir, X-Hub-Signature-256 değerini kontrol eder ve Page'i feed, messages ve mention alanlarına abone eder; ardından olayları, o Page'e özel sırla X-EC-Signature ile imzalanmış olarak HTTPS uç noktanıza iletir.

subscribe

hub.mode, Meta'nın doğrulama isteğinde her zaman taşıdığı değerdir; hub.challenge ise geri gönderilecek bir tam sayıdır.

sha256=

X-Hub-Signature-256 öneki, Meta'nın payload ve App Secret'tan ürettiği SHA256 imzasının önüne gelir.

5 seconds

Messenger webhook uç noktasının her bildirime ne kadar hızlı 200 OK ile yanıt vermesi gerektiği.

1 hour

Webhooks Disabled uyarısından ve uygulamanın Page aboneliğinin iptal edilmesinden önce, başarısız teslimat sayısı.

36 hours

Meta'nın, başarısız bir Page bildirimini düşürmeden önce azalan sıklıkla ne kadar süreyle yeniden denediği.

Meta'nın doğrulama isteği neler içerir?

Webhooks ürünü App Dashboard'da yapılandırıldığında ya da /{app-id}/subscriptions üzerinden bir abonelik oluşturulduğunda, geri çağırma URL'sine bir GET gönderilir. Bu istekle birlikte üç sorgu parametresi gelir:

  • hub.mode: her zaman subscribe.
  • hub.challenge: uç noktanın geri göndermesi gereken bir tam sayı.
  • hub.verify_token: App Dashboard'daki Verify Token alanına girilen dize.
  • PHP noktaları alt çizgiye çevirir, bu yüzden bunları hub_mode, hub_challenge ve hub_verify_token olarak okur.

Uç nokta buna nasıl yanıt vermelidir?

Yanıt, yalnızca hub.mode subscribe olduğunda ve hub.verify_token eşleştiğinde, gövdesi tamamen hub.challenge değeri olan bir 200 olarak verilir; diğer her durum, Meta'nın örnek uygulamasındaki gibi 403 alır. App Dashboard uç noktanın geçip geçmediğini bildirir; /{app-id}/subscriptions ise başarı ya da hata ile yanıt verir. Uç noktanın geçerli bir TLS veya SSL sertifikasıyla HTTPS kullanması gerekir, çünkü kendinden imzalı sertifikalar desteklenmez.

X-Hub-Signature-256 nasıl hesaplanır?

İstek payload'unun, uygulamanın App Secret'ı ile anahtarlanmış HMAC-SHA256 değeri olarak hesaplanır ve sha256= ardından küçük harfli hex olarak yazılır. Meta'nın Messenger rehberi, imzanın Unicode karakterleri kaçışlı olarak yazılmış payload üzerinden hesaplandığını ekler; böylece äöå gibi bir dize \u00e4\u00f6\u00e5 sayılır. Gövdeyi alındığı gibi, ham haliyle hash edin; asla çözülmüş ya da yeniden serileştirilmiş bir kopya değil. Meta, doğrulamanın isteğe bağlı olduğunu, ancak kesinlikle önerdiğini belirtir.

Kodda nasıl kontrol edilir?

Ham baytları saklayın, HMAC'i hesaplayın, sabit sürede karşılaştırın, sonra ayrıştırın. Flask'ın get_data fonksiyonu gövdeyi olduğu gibi döndürür; imza tam da bu üzerinden hesaplanmıştır. Önce ayrıştırıp sonra yeniden serileştirmek baytları değiştirirdi. Doğrulamayı yanıtlayan ve her POST'u kontrol eden küçük bir uç nokta:

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 doğrulamadan sonra ne bekler?

Her bildirim için 200 OK; Messenger olaylarında 5 saniye içinde. Meta, teslimat başına 1.000 güncellemeye kadar toplu gönderir, ancak bunu garanti etmez; hataları şöyle ele alır:

  • Page bildirimleri: hemen yeniden denenir, ardından 36 saat boyunca azalan sıklıkla birkaç kez daha denenir, sonra düşürülür.
  • Messenger bildirimleri: hemen birkaç kez yeniden denenir; 15 dakika süren hatalardan sonra geliştirici hesabına bir uyarı ulaşır.
  • Bir saatlik hatanın ardından Webhooks Disabled uyarısı gelir ve uygulama, yeniden abone olana kadar Page aboneliğinden çıkarılır.
  • Yeniden denemeler bir olayı iki kez ve sırasız teslim edebilir; bu yüzden tekilleştirin ve mesajları zaman damgasına göre sıralayın.
  • Geçmiş bildirimler sonradan sorgulanamaz; bu nedenle ihtiyacınız olanı geldiği anda saklayın.

easyCoexistence, Meta'nın kontrollerini nasıl geçer?

Meta uygulamasının, bağladığı Page'ler için tek bir geri çağırma URL'si vardır ve bu uç nokta iki kontrolü de kendisi yapar. GET isteğine yalnızca hub.mode subscribe olduğunda ve doğrulama token'ı eşleştiğinde, sabit sürede karşılaştırarak yanıt verir; aksi halde 403 döndürür. Her POST'u ham metin olarak okur, X-Hub-Signature-256 değerini uygulama sırrıyla yeniden hesaplar, uyuşmazlığı 401 ile reddeder ve olayı yanıttan sonra işleyerek Meta'ya hemen yanıt verir.

easyCoexistence ilettiği olayları nasıl imzalar?

Kendi imzasıyla, çünkü Meta'nın başlığı yalnızca easyCoexistence'ın uygulama sırrıyla kontrol edilebilir ve iletilmez. Ayarlanmış bir uç noktası olan bağlı her Page için her girdi, {platform, account_id, external_id, entry} biçiminde JSON olarak oraya POST edilir; istek, t=<unix>,v1=<hex> biçimindeki X-EC-Signature başlığını taşır. Burada v1, zaman damgasının, bir noktanın ve ham gövdenin HMAC-SHA256 değeridir; bu değer o Page'in imzalama sırrıyla anahtarlanır:

  • Sır whsec_ ile başlar ve set_social_webhook_destination ya da Partner API üzerindeki PUT /channels/:id/webhook ile yalnızca bir kez gösterilir.
  • URL'yi yeniden ayarlamak yeni bir sır üretir; URL'yi null yapmak iletmeyi kapatır.
  • Her iletim bir kez gönderilir; en fazla 8 saniye beklenir, yönlendirmeler izlenmez ve yalnızca genel bir IP'ye çözümlenen bir HTTPS adresine gönderilir.
  • Olayın bir kopyası tutulmaz; bu yüzden yeniden denenecek bir şey yoktur.

X-EC-Signature nasıl doğrulanır?

Başlığı t ve v1 olarak ayırın, 5 dakikadan eski bir zaman damgasını reddedin, Page'in imzalama sırrıyla t, bir nokta ve ham gövde üzerinden HMAC'i yeniden hesaplayın ve sabit sürede karşılaştırın. Node.js'te, gövdeyi ham bayt olarak tutarak:

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

Yaygın hatalar

  • hub.challenge'ı JSON ya da tırnak içine almak. 200 yanıtının gövdesi, challenge değerinin kendisi olmalıdır.
  • JSON ayrıştırıcısından sonra HMAC hesaplamak. Ayrıştırma ve yeniden serileştirme baytları değiştirir; Meta payload'u Unicode kaçışlı imzaladığı için ham gövdeyi hash edin.
  • Yanıt vermeden önce iş yapmak. Messenger 5 saniye içinde 200 bekler; bir saatlik hata, uygulamayı Page aboneliğinden çıkarır.
  • İletilen olaylarda Meta imzasını kontrol etmek. Meta, easyCoexistence'ın uygulama sırrıyla imzalar; iletilen bir olay X-EC-Signature taşır ve Page'in imzalama sırrıyla kontrol edilir.
Bunu EasyCoexistence'la yapmak

Bağlantı başına ve ayda US$ 9'dan US$ 0.75'e kadar, bağlantı ekledikçe düşen bir fiyatla. İlk 3 gün ücretsiz deneme.

Sık sorulan sorular

Doğrulama token'ını nereden alırım?

Onu siz seçersiniz. App Dashboard'da webhook'ları yapılandırırken Verify Token alanına girilen dize ya da /{app-id}/subscriptions uç noktasına gönderilen verify_token değeridir.

curl ile doğrulamayı test edebilir miyim?

Evet. Meta'nın Messenger rehberi hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED ve hub.mode=subscribe içeren bir GET gönderir; çalışan bir uç nokta CHALLENGE_ACCEPTED ile yanıt verir.

Uç noktam bir saat boyunca başarısız olursa ne olur?

Meta bir Webhooks Disabled uyarısı gönderir ve uygulamayı Page aboneliğinden çıkarır. Uç noktayı düzelttikten sonra Page'i subscribed_apps üzerinden yeniden abone edin.

Bir Page'in webhook'larını almak için kendi Meta uygulamam gerekir mi?

easyCoexistence ile gerekmez. Meta, olayları kendi uygulamasına teslim eder; uygulama da her Page'in olaylarını, sizin ayarladığınız uç noktaya X-EC-Signature ile imzalanmış olarak iletir.

Okumaya devam edin

İlk kanalınızı iki dakikada bağlayın.

Beklemeniz gereken platform incelemesi yok. WhatsApp, Instagram, TikTok veya başka bir kanalı bağlayın, ardından yapay zekânızdan paylaşım yapmasını, yanıtlamasını ya da rapor vermesini isteyin ve işini izleyin.

  • 3 gün ücretsiz
  • İstediğiniz zaman iptal
  • Yalnızca resmi API'ler
  • 7/24 izleniyor

Doğrulama tarihi