WhatsApp mesajları sunucunuza nasıl ulaşır: doğrudan ya da yönetilen; imzanın doğrulanması
easyCoexistence'e bağlanan her numaranın tek bir gelen mesaj modu vardır. Doğrudan sisteminize (doğrudan): Meta webhook'larını HTTPS uç noktanıza gönderir, URL'deki gizli anahtar kimlik bilgisidir ve otomasyonlar kapalıdır. easyCoexistence üzerinden (yönetilen): Meta easyCoexistence'e teslim eder, otomasyonlar yanıtlayabilir ve isteğe bağlı bir Forward URL'ye, Meta'nın gönderdiği value alanı bağlantı ayrıntılarıyla birlikte iletilir; X-EC-Signature ile imzalanır, doğrulayabilmeniz için.
İletilen her teslimat için denemeler: 1 dk, 5 dk, 30 dk, 2 sa, 6 sa ve 24 sa aralıklarla, toplamda yaklaşık 33 saat.
Her iletim denemesinin 2xx yanıtını ne kadar bekleyeceği; bu süre sonunda başarısız sayılır.
İmzadaki t değerinin yaşı için önerilen sınır; yeniden denemeler yeniden imzalanır, bu yüzden gerçek teslimatlar sınır içinde kalır.
Meta'nın HTTP 200 dışında herhangi bir yanıt alan doğrudan webhook'u ne kadar süreyle yeniden denediği; bu, mesajların tekrarlanmasına yol açabilir.
Meta'nın gönderdiği en büyük webhook payload'ı, geçmiş parçaları dahil.
Yönetilen bir numara için çalıştırma kayıtları, mesaj ve yanıt metniyle birlikte tutulur; mesaj metninin kendisi 30, 90 veya 365 gün saklanır, seçim sizindir.
Doğrudan ve yönetilen arasındaki fark nedir?
Meta'nın numaranın mesaj webhook'larını nereye teslim ettiği. Yönetilen, arayüzde “easyCoexistence üzerinden” olarak gösterilir: Meta easyCoexistence'e teslim eder; easyCoexistence Meta'nın imzasını kontrol eder, otomasyonlarınızı çalıştırır, sohbetleri Konuşmalar için saklar ve bir Forward URL ayarladıysanız, Meta'nın her değişikliğini yalnızca sizin bildiğiniz bir gizli anahtarla imzalayarak size iletir. Doğrudan, arayüzde “Doğrudan sisteminize” olarak gösterilir: easyCoexistence, numaranın WhatsApp Business Hesabı üzerinde HTTPS uç noktanızı webhook geçersiz kılma olarak ayarlar; Meta size doğrudan gönderir ve mesajlar easyCoexistence'e hiç uğramaz.
İzleme ve uyarıların arkasındaki operasyonel webhook'lar, örneğin account_update ve kalite değişiklikleri, her iki modda da easyCoexistence'de kalır; bu yüzden uyarılar her durumda çalışmaya devam eder.
| Managed: Through easyCoexistence | Direct: Straight to your system | |
|---|---|---|
| Meta delivers to | easyCoexistence, which verifies Meta's signature | Your HTTPS endpoint |
| Automations | Run on the number | Off |
| Your copy | Optional Forward URL, one Meta change per POST | Meta's envelope, unchanged |
| Proof it is genuine | X-EC-Signature, HMAC-SHA256 with the number's secret | A long random secret in the URL path |
| Failed deliveries | 7 attempts over about 33 hours | Meta retries for up to 7 days |
| History import | Not requested | Requested when saved within 24 hours of connecting |
| Kept by easyCoexistence | Message text 30, 90 or 365 days, run logs 30 days | Nothing |
Numarayı ikisi arasında nasıl geçirirsiniz?
Numaranın sayfasındaki Gelen mesajlar nereye gider kartı modu iki seçenek olarak gösterir: easyCoexistence üzerinden ve Doğrudan sisteminize. Kendi webhook'unuza yönlendirin kartında veya set_webhook_destination ile bir webhook hedefi kaydetmek numarayı doğrudan yapar. easyCoexistence üzerinden seçeneğini seçmek bu hedefi Meta'da hemen kaldırır; almaya devam etmek için aynı URL'yi Forward URL olarak ekleyin. Numara yönetilen moddan çıktığında sıradaki iletimler silinir; webhook URL'si olmadan bağlanan numaralar yönetilen modda başlar.
AI asistanınızdan set_inbound_mode modu değiştirir ve iletimi tek çağrıda ayarlar; iletim sırrını yalnızca bir kez döndürür:
// set_inbound_mode arguments
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward"
}
// result: forward_secret is shown once
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward",
"forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
"secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
"direct_destination": null
}İletilen bir POST neyi içerir?
Meta'nın object, entry ve changes zarfı yerine her istekte tek bir Meta değişikliği, sarmalanmış olarak. id teslimat kimliğidir, X-EC-Delivery başlığında da tekrar eder ve yeniden denemelerde sabit kalır. event, Meta alan adıdır: messages, smb_message_echoes, history veya smb_app_state_sync; X-EC-Event başlığında da tekrar eder. received_at, easyCoexistence'in değişikliği Meta'dan aldığı andır; connection numarayı tanımlar; value ise Meta'nın gönderdiğinin aynısıdır, bu yüzden Meta payload'ı için yazılmış ayrıştırma kodu bunda da çalışır. Teslimat durumları messages olaylarının içinde, value.statuses altında gelir.
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>
{
"id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
"event": "messages",
"received_at": "2026-11-11T14:02:11.482Z",
"connection": {
"id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"phone": "+1 631-555-0142",
"phone_number_id": "106540352242922",
"waba_id": "102290129340398",
"external_ref": null
},
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
"contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
"messages": [{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
"timestamp": "1794405731",
"type": "text",
"text": { "body": "Do you deliver on Sundays?" }
}]
}
}Node.js'te X-EC-Signature nasıl doğrulanır?
Başlığı t=<unix saniye>,v1=<64 onaltılık karakter> olarak okuyun. Saatinizden 5 dakikadan fazla uzaktaki bir t'yi reddedin; t, bir nokta ve ham gövde üzerinden HMAC-SHA256 hesaplayın; anahtar olarak tüm iletim sırrını UTF-8 metin olarak kullanın ve sonucu v1 ile sabit zamanlı olarak karşılaştırın. Bundan sonra JSON'u ayrıştırın. 10 saniye içinde 2xx yanıtı verin, işi sonra yapın ve kabul ettiğiniz teslimat kimliklerini hatırlayın ki bir yeniden deneme iki kez işlenmesin.
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production
export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
if (!m || !secret) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // a 2xx within 10 s, before any work
const d = JSON.parse(raw.toString("utf8"));
if (taken.has(d.id)) return; // a retry of a delivery already accepted
taken.add(d.id);
// d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
// d.value is Meta's change value, unchanged; queue it for your worker here.
console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
});
}).listen(process.env.PORT ?? 3000);Python'da nasıl doğrularsınız?
Standart kütüphaneyle aynı dört kontrol: başlık için katı bir desen, t'nin yaşı, t, bir nokta ve ham baytlar üzerinde hmac.new, ve hmac.compare_digest. FastAPI'de ham gövde await request.body() ile gelir, BackgroundTasks ise 200 gönderildikten sonra işi çalıştırır. Flask'ta request.get_data() kullanın; gövdeyi asla json.dumps ile yeniden kurmayın, çünkü Python'un varsayılan ayırıcıları boşluk ekler ve imza artık eşleşmez.
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response
app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode() # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set() # delivery ids already accepted: use a database in production
def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
m = SIGNATURE.fullmatch(header.strip())
if not m or abs(int(time.time()) - int(m[1])) > max_age:
return False
mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, m[2])
def process(delivery: dict) -> None:
if delivery["id"] in taken: # a retry of a delivery already accepted
return
taken.add(delivery["id"])
print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))
@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
raw = await request.body()
if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
return Response(status_code=401)
tasks.add_task(process, json.loads(raw)) # runs after the 200 goes out
return Response(status_code=200)Başarısız teslimatlar nasıl yeniden denenir?
Bir iletim, uç noktanız 10 saniye içinde herhangi bir 2xx yanıtı verdiğinde teslim edilmiş sayılır. Başka her şey (zaman aşımı, 4xx, 5xx veya takip edilmeyen bir yönlendirme) bir sonraki denemeyi yaklaşık 1 dakika, 5 dakika, 30 dakika, 2 saat, 6 saat ve 24 saat sonra planlar; yedinci denemeden sonra teslimat terk edilir. Her deneme taze bir t ile yeniden imzalanır; URL herkese açık HTTPS olmalıdır, kaydedilirken ve her gönderimden önce kontrol edilir. Teslimatlar en eskiden başlayarak gider, ancak yeniden denenen bir teslimat yenilerinden sonra ulaşabilir; bu yüzden Meta'nın zaman damgalarına göre sıralayın.
Doğrudan hedefte yeniden denemeyi Meta yapar: HTTP 200 dışındaki her yanıt, 7 güne kadar giderek azalan sıklıkla yeniden denenir ve bu yeniden denemeler bir mesajı tekrarlayabilir. İki modda da Meta'nın mesaj kimliğine göre tekilleştirin; Meta'nın yeniden gönderdiği bir değişiklik yeni bir teslimat kimliğiyle yeniden iletilir.
Doğrudan bir uç nokta POST'un gerçek olduğunu nasıl anlar?
X-Hub-Signature-256 başlığından değil. Meta, aboneliğin sahibi uygulamanın uygulama sırrıyla imzalar; burada bağlanan bir numara için bu easyCoexistence'in sırrıdır ve paylaşılmaz; bu yüzden o başlığı kendi Meta uygulama sırrınızla kontrol etmek gerçek teslimatları reddeder. Doğrulama token'ı yalnızca bir kez, Meta'nın GET el sıkışması sırasında uç noktayı kanıtlar. Bunun yerine işe yarayan yollar:
- Geri arama URL'sinin yoluna 32 veya daha fazla rastgele karakter ekleyin ve bunlar olmayan istekleri reddedin; değiştirmek için yeni bir URL kaydedin.
- Kendi Meta uygulamanızı bekleyen bir WhatsApp tetikleyicisi yerine, n8n Webhook düğümü gibi genel bir alıcı kullanın.
- Medyayı kimliğine göre, numaranın token'ıyla Meta'dan indirin; sahte bir kimlik basitçe başarısız olur.
- Kendi barındırdığınız sunucularda isteğe bağlı olarak yalnızca Meta'nın ağına, AS32934'ün duyurduğu yollara izin verebilirsiniz.
- Ya da Forward URL ile yönetilen moda geçin; burada X-EC-Signature her POST'u kanıtlar.
Yaygın hatalar
- Meta'nın zarfı için yazılmış kodu hiç değiştirmeden Forward URL'ye yöneltmek. Bir iletim tek bir değişiklik taşır: event ve value alanlarını okuyun, object, entry ve changes alanlarını değil.
- X-EC-Event değerinin statuses olmasını beklemek. Teslimat durumları messages olaylarının içinde, value.statuses altında gelir; uygulamada yazılan yanıtlar smb_message_echoes olarak gelir.
- Yanıt vermeden önce işi yapmak. İletim 10 saniye bekler, sonra aynı teslimat yeni bir t ile geri döner; önce 2xx yanıtı verin ve işi bir kuyruktan işleyin.
- Yönetilen moda geçip eski URL'nin hâlâ aldığını varsaymak. Doğrudan hedef o anda kaldırılır; forward_url parametresini aynı set_inbound_mode çağrısında iletin.
easyCoexistence, bir WhatsApp Business uygulama numarasını Coexistence aracılığıyla Meta'nın Cloud API'sine bağlar ve her numara için mesajlarının nereye gideceğini seçmenize izin verir: doğrudan Meta'dan sunucunuza ya da otomasyonların yanıt verebilmesi ve imzalı bir kopyanın Forward URL'nize ulaşabilmesi için easyCoexistence üzerinden. İzleme ve uyarılar iki modda da çalışır. Numara başına aylık US$ 9'dan US$ 0.75'e kadar, numara ekledikçe düşer; ilk 3 gün ücretsiz deneme.
Sık sorulan sorular
Sunucum bir otomasyonun neyle yanıt verdiğini görür mü?
Metni değil. Meta API gönderimlerini messages olayları içinde durum olarak bildirir (gönderildi, iletildi, okundu), mesaj kimliğiyle birlikte; metnin kendisi otomasyonun çalıştırma kaydında, Çalıştırmalar sekmesinde 30 gün, Konuşmalar'da ise seçtiğiniz süre boyunca tutulur.
İletim sırrını nasıl döndürürüm?
Numaranın sayfasındaki Yeni sır düğmesine tıklayın ya da set_inbound_mode çağrısında rotate_secret değerini true yapın. Yeni sır yalnızca bir kez gösterilir ve o andan itibaren her şeyi imzalar; eski teslimatların yeniden denemeleri de dahil, bu yüzden sunucunuzu hemen güncelleyin.
Forward URL, Meta'nın GET el sıkışmasını gerektirir mi?
Hayır. Yalnızca doğrudan hedef Meta tarafından çağrılır ve hub.challenge değerini geri göndermesi gerekir. Forward URL easyCoexistence tarafından çağrılır ve yalnızca imzalı POST alır.
Bir numara aynı anda hem doğrudan hedefe hem de Forward URL'ye sahip olabilir mi?
Hayır. Forward URL yalnızca numara yönetilen moddayken çalışır ve doğrudan hedef kaydetmek numarayı doğrudan yapar. Forward URL ile sırrı korunur; bu yüzden yönetilen moda geri döndüğünüzde iletim kaldığı yerden devam eder.
Okumaya devam edin
Başlamaya hazır mısınız?
WhatsApp Coexistence'ı aylar değil, dakikalar içinde kurun. Uygulama telefonda çalışmaya devam eder.
Ücretsiz denemeyi başlatınDoğrulama tarihi