Ana içeriğe atla
Giden web kancaları, sistemlerinizin API’yi sorgulamadan Flowella’deki olaylara neredeyse gerçek zamanlı olarak tepki vermesini sağlar. Bir URL ve olay türlerinin bir listesini yapılandırırsınız ve Flowella bu olaylardan biri her ateşlendiğinde bu URL’ye imzalı bir JSON yükü POST eder.

​
Bir web kancası yapılandırma

Sahip** veya Yönetici rolüne ihtiyacınız var.
1

Ayarlar → Web Kancaları'nı açın

Flowella uygulamasında Ayarlar → Web Kancaları bölümüne gidin.
2

Web kancası ekleme

Webhook ekle** seçeneğine tıklayın, uç noktanızın genel HTTPS URL’sini yapıştırın ve almak istediğiniz olay türlerini seçin.
3

İmzalama sırrını kaydedin

Flowella web kancası için benzersiz bir imzalama sırrı oluşturur. Kopyalayın - gelen talepleri doğrulamak için kullanacaksınız.
4

Bir test gönderin

Hemen bir webhook.test yükü göndermek için Send test seçeneğine tıklayın. Uç noktanızın bunu aldığını ve 2xx ile yanıt verdiğini kontrol edin.

​
Olay türleri

Bu ürün etkinliklerinden herhangi birine abone olabilirsiniz:
OlayAteşlendiğinde
message.receivedBir kişiden gelen bir WhatsApp mesajı geldi
message.sentFlowella giden mesajınızı kabul etti ve Meta’ye gönderdi
message.deliveredMeta mesajın alıcının cihazına teslim edildiğini doğruladı
message.readAlıcı mesajı açtı
message.failedMeta mesajı için bir hata döndürdü
conversation.openedBir görüşme açık duruma geçti
conversation.closedBir görüşme kapatıldı
optout.createdBir kişi belirli bir kanalda devre dışı bırakıldı
template.status_updatedMeta bir şablonun durumunu değiştirdi (onaylandı, reddedildi, duraklatıldı, devre dışı bırakıldı)
webhook.test yalnızca Test gönder seçeneğine tıkladığınızda gönderilir - buna açıkça abone olmazsınız.

​
İstek biçimi

Flowella URL’nize bu başlıklarla birlikte bir JSON gövdesi POST eder: 
POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella-Webhooks/1
X-Flowella-Signature: <hex digest>
Yükler 256 KB ile sınırlandırılmıştır. Daha büyük nesneler özetlenir - ihtiyacınız varsa tüm kaydı kimliğe göre almak için API’yi kullanın. Vücut şekli etkinliğe göre değişir ancak her zaman şunları içerir: 
{
  "event": "message.delivered",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "...event-specific fields..." }
}

​
İmzaların doğrulanması

Her istek bir X-Flowella-Signature başlığı içerir. Değer, web kancanızın imzalama sırrı ile anahtarlanmış raw UTF-8 istek gövdesinin HMAC-SHA256 onaltılı özetidir. İşleme almadan önce doğrulayın: 
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)
Herhangi bir JSON ayrıştırma veya ara yazılım yükü yeniden biçimlendirmeden önce her zaman ham gövde baytları üzerinden imzalayın. Çerçeveniz JSON’u yeniden serileştiriyorsa, imza eşleşmeyecektir.

​
Yanıtlar, yeniden denemeler ve zaman aşımları

  • Zaman aşımı**: Flowella, uç noktanızın yanıt vermesi için 10 saniye kadar bekler.
  • Başarılı**: herhangi bir 2xx yanıtı başarılı teslimat olarak kabul edilir.
  • Yeniden denemeler**: başarısız teslimatlar, geri alma ile 3 denemeye kadar yeniden denenir.
  • Otomatik devre dışı bırakma**: bir web kancası 10 ardışık başarısızlık biriktirirse, Flowella onu devre dışı bırakır. Uç noktanızı düzelttikten sonra Ayarlar → Web Kancaları bölümünden yeniden etkinleştirmeniz gerekecektir.
Uç noktanız mümkün olduğunca hızlı dönmelidir - ağır işlemleri kendi tarafınızdaki bir arka plan kuyruğuna erteleyin.

​
Idempotency

Web kancaları yeniden denenebilir, bu nedenle aynı mantıksal olay birden fazla kez gelebilir. Güvenli bir şekilde işlemek için:
  • Olayın data.id’sini (veya event + data.messageId gibi türetilmiş bir anahtarı) idempotans anahtarı olarak kullanın.
  • İşlenmiş anahtarların kısa ömürlü bir önbelleğini tutun (yeniden denemeler için birkaç saat yeterlidir).
  • Mükerrerlere işlem yapılmayacakmış gibi davranın.

​
Teslimatları listeleme ve yönetme

Ayarlar → Web Kancaları web kancası başına son teslimat denemelerini gösterir:
  • Zaman Damgası
  • Etkinlik türü
  • Yanıt durumu
  • Hata ayıklama için kesilmiş bir yanıt gövdesi (~1 KB’a kadar)
Bir web kancası tekrarlanan hatalar nedeniyle devre dışı bırakılırsa, aynı sayfa onu yeniden etkinleştirmenizi sağlar.

​
Yerel kalkınma

Yerel olarak web kancalarına karşı geliştirme yapmanın en basit yolu, genel bir tüneli (örneğin, ngrok veya Cloudflare Tunnel) geliştirme sunucunuza yönlendirmek ve web kancası URL’sini tünel ana bilgisayarına yönlendirmektir. Gerçek WhatsApp etkinliğini beklemeden talep üzerine yükleri ateşlemek için Send test kullanın.
Listede olmayan etkinliklere tepki vermeniz mi gerekiyor? Bize support adresinden bildirin - müşterilerimiz talep ettikçe etkinlikler ekliyoruz.

​
İlgili

Ayarlar → Web kancaları

Uygulamada uç noktaları, imzalama gizli dizilerini ve yeniden denemeleri yapılandırın.

API tanıtımı

REST API için kimlik doğrulama, hatalar, sayfalandırma ve oran sınırları.

API anahtarları

Uç noktanızın ihtiyaç duyabileceği taşıyıcı belirteçleri oluşturun ve döndürün.

Bildirim etkinlikleri

Aynı etkinlikler uygulama içi akışa ve e-postaya iletilir.