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

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

Instagram webhook'ları kurmak için, Meta'nın doğrulama GET isteğine yanıt veren bir HTTPS uç noktası gerekir. Bu istek hub.mode değerini subscribe olarak, ayrıca hub.verify_token ve hub.challenge alanlarını taşır; uç nokta token'ı kontrol edip challenge değerini döndürür. Uygulama alanlara abone olduktan ve her hesap subscribed_apps kenarı üzerinden abone edildikten sonra Meta, uygulamanın gizli anahtarıyla X-Hub-Signature-256 başlığında imzalanmış JSON olayları gönderir.

easyCoexistence Meta tarafını yönetir: uygulaması doğrulamayı geçer, X-Hub-Signature-256 değerini kontrol eder, bağlı her Instagram hesabını yorumlara, mesajlara ve bahsetmelere abone eder ve olayları, X-EC-Signature ve hesap başına bir gizli anahtarla imzalanmış olarak HTTPS uç noktanıza iletir; her bağlantıyı da 7/24 izler.

subscribe

hub.mode değeri, Meta'nın doğrulama isteğinde her zaman bulunur.

36 hours

Meta'nın başarısız bir bildirimi düşürmeden önce, giderek seyrekleşen aralıklarla yeniden denediği süre.

15 minutes

Meta'nın geliştirici hesabına uyarı göndermeden önce gereken başarısız mesaj iletimi sayısı.

1 hour

Webhooks Disabled uyarısından ve uygulamanın hesaptan çıkarılmasından önceki başarısız mesaj iletimi sayısı.

Live

Meta'nın, uygulamanın kullanıcılarının hesapları için bildirim almasından önce gerektirdiği uygulama modu.

Instagram webhook kurulumu nasıl çalışır?

Meta'nın kılavuzunda verilen sırayla dört adımda. Uç nokta, herhangi bir alan seçilmeden önce doğrulamayı geçmelidir; uygulamanın kullanıcılarının hesapları için bildirim alabilmesi için Live modunda olması gerekir ve üretim erişimi için işletme doğrulaması zorunludur.

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

Doğrulama isteği neleri içerir?

Webhooks ürünü uygulama panelinde yapılandırıldığında, geri çağırma URL'sine bir GET isteği gönderilir. hub.verify_token, uç noktanın kendi token'ıyla eşleşirse, yanıt tüm gövde olarak hub.challenge değerini içeren bir 200 olur; aksi halde 403 döner. Panel, uç noktanın doğrulamayı geçip geçmediğini bildirir.

  • hub.mode: her zaman subscribe.
  • hub.challenge: Meta'nın ürettiği bir tamsayı; uç noktanın bunu geri göndermesi gerekir.
  • hub.verify_token: panelin Verify Token alanına girilen dize; yalnızca Meta ve uç nokta bilmelidir.
  • PHP'de bu adlardaki noktalar alt çizgiye dönüşür; değerler hub_mode, hub_challenge ve hub_verify_token olarak gelir.
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

Geri çağırma ve alanlar nerede ayarlanır?

Uygulama panelinde, Instagram altında, API setup with Instagram login ve Configure webhooks bölümünde geri çağırma URL'si ve doğrulama token'ı girilir; kaydedildiğinde doğrulama isteği gönderilir. Instagram ürünü başlangıçta comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral ve messaging_seen alanlarına abone olarak başlar; Manage ile bunlardan herhangi birinin aboneliği iptal edilebilir. Test düğmesi, seçilen bir alan için örnek bir bildirim gönderir.

X-Hub-Signature-256 nasıl kontrol edilir?

Meta her olay bildirimini, payload üzerinde uygulamanın gizli anahtarıyla oluşturulan bir HMAC-SHA256 ile imzalar ve bunu X-Hub-Signature-256 başlığında sha256= ön ekiyle, ardından onaltılık (hex) özet olarak gönderir. Alıcı, ham istek gövdesi üzerinde aynı HMAC'i hesaplar ve sabit sürede başlıkla karşılaştırır. Meta'nın mesajlaşma kılavuzu, imzanın Unicode kaçışlı payload'u kapsadığını belirtir; bu nedenle çözülmüş veya yeniden serileştirilmiş JSON'un hash'lenmesi farklı bir sonuç verir.

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

Neden yalnızca uygulamanın gizli anahtarı kontrol edebilir?

Çünkü imza, bu anahtarla anahtarlanmış bir HMAC'tir. Anahtar olmadan beklenen değeri kimse hesaplayamaz; bir payload'un kopyasına sahip olan biri de sahte bir tane üretemez. Bu nedenle kontrol, uygulama için Meta'nın isteklerini alan sunucuda yapılmalıdır. Meta, uygulama gizli anahtarlarının, erişim token'larının ve istemci kimlik bilgilerinin günlüklerde ve destek taleplerinde yer almamasını ister. Başka bir uygulama tarafından iletilen olayları alan bir sistem, Meta'nın imzasını hiç kontrol edemez ve bunun yerine o uygulamanın kendi imzasına güvenir.

Neden her hesabın kendi aboneliği olmalı?

Çünkü uygulama panelinde uygulamanın neyi alabileceği belirlenir, ama bir hesap için bildirimler yalnızca o hesap da abone edildiğinde başlar. Instagram Login ile, graph.instagram.com adresine, hesabın Instagram User erişim token'ıyla ve uygulama için seçilen alanları virgülle ayırarak listeleyen subscribed_fields parametresiyle POST /<IG_ID>/subscribed_apps isteği gönderin. Başarılı bir çağrı success değerini true olarak döndürür.

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 }

Meta teslimatlar başarısız olduğunda ne yapar?

Yeniden dener, sonra vazgeçer. Meta'nın kılavuzu her bildirim için 200 OK bekler ve 1.000 güncellemeye kadar toplu gönderimin garanti edilmediği konusunda uyarır. Başarısız bir güncelleme hemen yeniden denenir, sonra 36 saat boyunca giderek seyrekleşen aralıklarla birkaç kez daha denenir ve bundan sonra düşürülür; bu nedenle aynı olay iki kez gelebilir. Mesajlaşma olayları daha hızlı işleyen Meta mesajlaşma teslimat kurallarını izler:

  • Her bildirim için 5 saniye içinde 200 OK beklenir; başarısız bir teslimat hemen birkaç yeniden denemeye tabi tutulur, bu yüzden mid değerine göre tekilleştirin.
  • 15 dakika boyunca başarısızlık yaşanırsa, geliştirici hesabına bir uyarı gider.
  • Bir saat boyunca başarısızlık yaşanırsa Webhooks Disabled uyarısı gelir ve uygulamanın aboneliği, yeniden abone olunana kadar hesabın webhook'larından iptal edilir.
  • Kesinti sırasında gönderilen mesajlar sırasız gelebilir; bu nedenle zaman damgasına göre sıralayın.

Hiçbir şey gelmediğinde neyi kontrol etmelisiniz?

Sessiz uç noktaların çoğunu kapsayan Meta sorun giderme kontrol listesi, şu sırayla:

  • Geri çağırma URL'si kontrolden geçti ve geçerli bir sertifikayla HTTPS üzerinden erişilebilir; kendinden imzalı sertifikalar desteklenmez.
  • Uygulama alanı seçti ve gereken erişim düzeyine sahip; comments ve live_comments için Advanced Access.
  • Bildirimler, aynı giriş kurulumundan bir token ile subscribed_apps üzerinden hesap için etkinleştirildi.
  • Hesap alanın kurallarını karşılıyor: yorum bildirimleri, herkese açık bir hesaba ait medya gerektirir.
  • Sunucu, yavaş işe başlamadan önce success yanıtı döndürür.

easyCoexistence iletilen olayları neden yeniden imzalar?

Çünkü Meta'nın imzası iletilemez. easyCoexistence'ın uygulaması Meta'nın teslimatını alır, X-Hub-Signature-256 değerini kendi uygulama gizli anahtarıyla kontrol eder, Meta'ya hemen yanıt verir ve bağlı bir hesaba ait her girdiyi, o hesap için belirlenen uç noktaya, platform, account_id, external_id ve entry alanlarından oluşan yeni bir gövde içinde POST eder. Meta'nın başlığı iletilmez ve o gizli anahtar olmadan kontrol edilemezdi; bu yüzden her iletim, yalnızca o tek hesaba ait bir anahtarla imzalanmış X-EC-Signature başlığını ve Content-Type: application/json başlığını taşır.

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

Başlık t=<unix>,v1=<hex> biçimindedir; burada v1, zaman damgasının, bir noktanın ve ham gövdenin hex olarak HMAC-SHA256 değeridir ve hesabın imza gizli anahtarıyla anahtarlanmıştır. Alınan baytlar üzerinden tam olarak yeniden hesaplayın, sabit sürede karşılaştırın ve 5 dakikadan eski bir zaman damgasını reddedin.

  • Gizli anahtar whsec_ ile başlar ve URL ayarlandığında set_social_webhook_destination veya PUT /channels/:id/webhook ile yalnızca bir kez gösterilir.
  • URL yeniden ayarlanırsa yeni bir gizli anahtar üretilir; URL null olarak ayarlanırsa iletim kapanır.
  • Her olay bir kez gönderilir; 8 saniyeye kadar beklenir, yönlendirmeler izlenmez ve genel bir IP'ye çözümlenen bir HTTPS adresine gönderilir.
  • Bağlantı kaldırıldığında hesabın Meta webhook'larından aboneliği iptal edilir ve uç noktası ile gizli anahtarı silinir.
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())

Yaygın hatalar

  • Challenge değerini JSON olarak ya da tırnak içinde döndürmek. Meta, gövde olarak hub.challenge değerinin kendisini, 200 durum koduyla bekler.
  • Ayrıştırılmış gövdeyi hash'lemek. JSON gövde ayrıştırıcısı, Meta'nın imzaladığı tam baytları atar; bu yüzden HMAC için ham gövdeyi saklayın ve sonra ayrıştırın.
  • Uygulamayı abone edip hesabı unutmak. POST /<IG_ID>/subscribed_apps bir hesap için başarılı olana kadar o hesap için bildirim gelmez.
  • Bir uç noktanın bir saat boyunca başarısız olmasına izin vermek. Meta mesajlaşma webhook'larını devre dışı bırakır ve uygulamanın hesaptan aboneliğini iptal eder; hesabın yeniden abone edilmesi gerekir.
Bunu EasyCoexistence'la yapmak

set_social_webhook_destination veya Partner API ile etkinleştirin. Bağlantı başına aylık US$ 9 ile US$ 0.75 arasında, bağlantı ekledikçe düşer; ilk 3 gün ücretsiz deneme.

Sık sorulan sorular

Instagram webhook'larında hub.challenge nedir?

Meta'nın doğrulama GET isteğinde gönderdiği bir tamsayıdır. Uç nokta hub.verify_token değerini kontrol ettikten sonra bunu yanıt gövdesi olarak döndürür; bu da URL'yi kontrol ettiğini kanıtlar.

PHP'de hub.mode ve hub.challenge neden eksik görünür?

PHP, parametre adlarındaki noktaları alt çizgiye çevirir; bu nedenle Meta'nın doğrulama değerleri hub_mode, hub_challenge ve hub_verify_token olarak gelir.

Meta bunları devre dışı bıraktıktan sonra Instagram webhook'larını nasıl yeniden açabilirsiniz?

Uç noktayı düzeltin, sonra aynı alanlarla POST /<IG_ID>/subscribed_apps kullanarak hesaba yeniden abone olun.

Instagram webhook uç noktası için kendinden imzalı sertifika çalışır mı?

Hayır, Meta kendinden imzalı sertifikaları desteklemez: geri çağırma URL'si, Meta sorun giderme kontrol listesinin ilk maddesi olarak, geçerli bir sertifikayla HTTPS üzerinden erişilebilir olmalıdır.

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