WhatsApp Webhook Rehberi: Olaylar, Güvenlik ve Yeniden Denemeler

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

Güvenilir bir işleyici nasıl yazarım?

Üç şeyi sırasıyla yapın: ham olayı saklayın, 2xx ile onaylayın, ardından asenkron işleyin. Aşağıdaki işleyici belgelerimizdeki deseni izler.

import express from "express";

const app = express();

// Ham gövdeyi, alındığı haliyle saklayabilmek için yakalayın.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // depolama başarısız: olayın yeniden denenmesine izin verin
    }
    res.sendStatus(200);          // hızla onaylayın
    queue.publish("status-events", req.body); // asıl işi başka yerde yapın
  },
);

// Worker: idempotent işleme
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // kanala göre eşleyin
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // bilinmeyen mesaj: günlüğe alın ve inceleyin
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // mükerrer veya eski

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # depolama başarısız: olayın yeniden denenmesine izin verin
    queue.publish("status-events", raw)  # asenkron işleyin
    return "", 200               # hızla onaylayın

db ve queue nesneleri sizin kendi depolamanız ve iş kuyruğunuzdur. rank eşlemesi işlemeyi idempotent yapan şeydir: mükerrer veya eski bir olay ilerleme değildir, bu yüzden yok sayılır.

Güvenilir bir işleyici için kurallar

• Birkaç saniye içinde yanıt verin. Yanıt vermeden önce ağır iş yapmayın.
• 2xx değerini yalnızca olay saklandıktan sonra döndürün. Depolama başarısız olursa 5xx döndürün.
• Mesaj kimliğine göre mükerrerleri ayıklayın. Aynı durum birden fazla kez gelebilir.
• Bir mesajı asla işleyiciden yeniden göndermeyin. Yeniden denemelere, durumu kontrol ettikten sonra ayrı bir işte karar verin.
• Ham gövdeyi saklayın; sorun giderme ve bir düzeltmeden sonra olayları tekrar oynatmak için.

WhatsApp webhook'unu nasıl güvenceye alırım?

Uç noktanıza kimin gönderdiğine bağlıdır. Meta, Meta'ya kaydettiğiniz uygulamalara gönderdiği webhook'ları imzalar. OmniChannels.ai API belirtimi bir webhook imza başlığı tanımlamaz; bu yüzden birini beklemeyin.

Meta'nın şeması için Meta'nın belgeleri, uygulama gizli anahtarınızı kullanarak JSON yükünden bir HMAC-SHA256 özeti üretmeyi ve X-Hub-Signature-256 başlığındaki sha256= sonrasındaki değerle karşılaştırmayı söyler. HMAC'in kendisi RFC 2104'te tanımlıdır. Yeniden serileştirilmiş bir nesne üzerinden değil ham baytlar üzerinden hesaplayın ve sabit zamanlı karşılaştırın.

Bizim uç noktamız için:

• Yalnızca geçerli bir sertifikayla HTTPS kullanın.
• Uzun, tahmin edilemez bir yol kullanın ve sızarsa değiştirin.
• Gövde şeklini doğrulayın ve beklenmeyen her şeyi reddedin.
• Olayları bildirim olarak ele alın. Geri ödeme veya dolandırıcılık kilidi gibi geri alınamaz bir eylemden önce durumu bir polling çağrısıyla teyit edin.

İletim başarısız olduğunda ne olur?

Yeniden denemeler göndericiye bağlıdır. Meta'nın belgeleri, başarısız bir iletimi azalan sıklıkla 7 güne kadar yeniden denediğini söyler; bu mükerrer bildirimlere yol açabilir. Mükerrerleri nadiren görseniz bile idempotent olmanın nedeni budur. Platformumuzdan gelen olaylar için, Meta'nınkiyle eşleştiğini varsaymak yerine yeniden deneme davranışını devreye alma mühendisinizle teyit edin.

Her iki durumda da kaybı da mükerrer kadar hesaba katın: uç noktanız bir dağıtım sırasında kapalı olabilir ve bir güvenlik duvarı kuralı istekleri sessizce düşürebilir.

Kayıp olayları nasıl kurtarırım?

Mesajı yeniden göndermeyin, batch'i sorgulayın.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id, gönderim çağrısının döndürdüğü kimliktir ve page sıfırdan başlar. Önceki günün batch'lerini okuyan ve boşlukları dolduran gecelik bir mutabakat çalıştırın.

Sorun giderme kontrol listesi

1. URL doğru hesapta veya alt hesapta mı yapılandırılmış?
2. Uç noktaya geçerli sertifikayla HTTPS üzerinden ulaşılabiliyor mu?
3. Hızla 2xx yanıtlıyor mu, yoksa zaman aşımına mı uğruyor?
4. Bir güvenlik duvarı veya WAF kuralı istekleri engelliyor mu?
5. Ayrıştırmadan önce ham gövdeyi günlüğe alıyor musunuz; böylece bir ayrıştırıcı hatası olayı gizleyemesin?

Örnek senaryo: Bir perakendecinin bildirim hattı

BAE'li bir perakendeci olan "Souq Rafiq" (kurgusal), sipariş güncellemelerini WhatsApp ile gönderiyor ve sipariş aracında doğru durum istiyor.

1. Siparişler sendbulk ile gönderilir ve batchId siparişte saklanır. Bkz. API ile WhatsApp mesajı gönderme.
2. Webhook uç noktası her olayı bir tabloya yazar, ardından 200 döndürür.
3. Bir worker durumları sıralar ve siparişin mesaj durumunu günceller.
4. FAILED olayları, nedeniyle birlikte destek için bir görev oluşturur ve kanal fallback uyarınca bir SMS fallback'i değerlendirilir.
5. Gelen müşteri mesajları, temsilciler pencere içinde yanıtlayabilsin diye ortak gelen kutusuna yönlendirilir.
6. Gecelik bir iş, dünkü batch'ler için bulk-insights'ı çağırır ve kaçırılanları düzeltir.

Yaygın hatalar nelerdir?

• Yanıt vermeden önce ağır iş; bu zaman aşımlarına ve tekrarlanan iletimlere yol açar.
• Saklamadan önce onaylamak; depolama başarısız olduğunda olayları kaybettirir.
• Sıraya güvenmek. Geç gelen bir SENT'in DELIVERED'ın üzerine yazması.
• Gerçek olaylar yerine açıklayıcı yüke karşı kod yazmak.
• İmzayı kontrol etmeden önce JSON'u yeniden serileştirmek; bu baytları değiştirir.
• İşleyiciden yeniden göndermek; bu döngüye girebilir.
• Limitler: bu rehber belgelenmiş davranışımızı anlatır. Hesabınız için yeniden deneme politikası ve yük alanları devreye alma sırasında teyit edilmelidir.

OmniChannels.ai nasıl yardımcı olur?

OmniChannels.ai, WhatsApp, SMS, RCS ve diğer kanallar için iletim durumlarını ve gelen mesajları tek bir normalleştirilmiş biçimde webhook'unuza iter; bayiler için alt hesap başına ayrı webhook'lar vardır. BroadNet resmi bir Meta Business Solution Provider'dır; bu yüzden Meta'nın kendi webhook gereksinimleri sizin yerinize karşılanır ve siz bizim API'mizle çalışırsınız. Webhook referansını ve WhatsApp API belgelerini okuyun veya olayların ortak gelen kutusunda nasıl göründüğüne bakın.