Brantial olaylarını Zapier, Make, n8n veya kendi sisteminize gönderme

Webhook, projenizin uyarılarını ve raporlarını gerçekleştikleri anda JSON olarak Zapier, Make, n8n ya da kendi sisteminize gönderir. Oradan istediğiniz araca iletebilir, bir tabloya satır ekleyebilir ya da kayıt açabilirsiniz. Bütün olaylar tek adrese gelir ve her istek imzalıdır, böylece Brantial’dan geldiğini kontrol edebilirsiniz.

Başlamadan önce

• Webhook’u yalnızca proje sahibi bağlayabilir.
• Adres herkese açık olmalı ve HTTPS kullanmalı. Yerel, özel ağ ve düz HTTP adresleri reddedilir.
• Bir projenin tek bir webhook adresi olur. Olayları birden fazla yere göndermek için iş akışınızda dağıtın.

Adres alma

Zapier

1. Bir Zap oluşturun ve tetikleyici olarak Webhooks by Zapier’ı seçin.
2. Catch Hook olayını seçip devam edin.
3. Zapier’ın gösterdiği webhook adresini kopyalayın. https://hooks.zapier.com/ ile başlar.

Make

1. Bir senaryo oluşturun ve Webhooks → Custom webhook modülünü ekleyin.
2. Add’e tıklayın, webhook’a bir ad verin ve kaydedin.
3. Make’in gösterdiği adresi kopyalayın ve dinlemeye devam etmesi için senaryoyu açın.

n8n

1. Bir Webhook düğümü ekleyin ve HTTP Method’u POST yapın.
2. Test adresini değil, Production URL’yi kopyalayın.
3. İş akışını etkinleştirin. Üretim adresi yalnızca iş akışı etkinken yanıt verir.

Kendi sisteminiz

JSON gövdeli bir POST isteğini kabul edip 2xx durum koduyla yanıt veren her HTTPS adresi olur.

Brantial’da bağlama

1. Brantial’da projenizi açın, Ayarlar’a gidin ve Bildirimler sekmesini açın.
2. Webhook kartında adresi Webhook adresi alanına yapıştırın.
3. Webhook’u bağla’ya tıklayın. Brantial önce bir test olayı gönderir ve adresi yalnızca kabul edilirse kaydeder.

Bağlantı kurulunca kart İmza anahtarını ve her olay için bir düğme gösterir. İstemediğiniz olayları kapatın; değişiklikler hemen kaydedilir. Test gönder istediğiniz an yeni bir test olayı gönderir; iş akışınızı kurarken işe yarar.

Brantial ne gönderir

Her olay aynı yapıdadır; bir iş akışı adımı olayı bilmeden title, text ve url alanlarını kullanabilir. Her olayın arkasındaki rakamlar data içindedir.

{
  "id": "6f1c2d4e-8a90-4b7c-9d2e-1f3a5b7c9d0e",
  "event": "report.summary",
  "created_at": "2026-10-26T07:00:00+00:00",
  "project": {
    "id": 1234,
    "name": "Example Outdoor",
    "domain": "example.com",
    "url": "https://app.brantial.ai/1234/overview"
  },
  "title": "Weekly report for Example Outdoor",
  "text": "Weekly report for Example Outdoor — visibility 42%, up 3 points.",
  "url": "https://app.brantial.ai/1234/overview",
  "data": {
    "cadence": "weekly",
    "period_start": "2026-10-19",
    "period_end": "2026-10-25",
    "metrics": {
      "visibility": { "value": 42, "change": 3 },
      "mentions": { "value": 118, "change": 12 },
      "average_position": { "value": 2.4, "change": -0.3 },
      "sentiment": { "value": 71, "change": 1 }
    },
    "strongest_prompts": [
      { "prompt": "best hiking boots for wide feet", "visibility": 80 }
    ]
  }
}

Yukarıdaki rakamlar örnektir. Her olayın data alanı:

Olay	Ne zaman	data
test	Bağlarken ya da Test gönder’e tıkladığınızda	Boş
report.summary	Her pazartesi; proje aylığa ayarlıysa ayda bir	cadence, period_start, period_end, metrics, strongest_prompts
site_audit.finished	Bir site denetimi bittiğinde ya da eşiklerinizi aştığında	audit_id, site_health_score, ai_readiness_score
visibility.changed	AI görünürlüğü bir haftada 10 puan veya daha fazla değiştiğinde	current, previous, delta, answers
competitors.new	AI, takip etmediğiniz bir markayı sürekli andığında	brands
optimization.finished	Optimize edilen sayfa hazır olduğunda ya da sizi beklediğinde	optimization_id, page_url, status
crawler_access.changed	Bir AI tarayıcısı engellendiğinde ya da izin verildiğinde	changes, unreachable

Her istekte ayrıca şu başlıklar bulunur:

• X-Brantial-Event: Olay adı; gövdedeki event ile aynı.
• X-Brantial-Delivery: Olayın id değeri. Yeniden denenen olay aynı kimliği taşır, böylece daha önce işlediğinizi atlayabilirsiniz.
• X-Brantial-Signature: Aşağıda anlatılan imza.

İmzayı kontrol etme

X-Brantial-Signature, sha256= ve ardından ham istek gövdesinin imza anahtarınızla hesaplanan HMAC-SHA256 değeridir. Aynı değeri kendi tarafınızda hesaplayıp karşılaştırın. Gövdeyi geldiği gibi kullanın: çatınız JSON’u önce çözüp yeniden kodlarsa imza tutmaz.

Zapier, Make ve n8n’de bu kontrol isteğe bağlıdır, çünkü adresi yalnızca Brantial bilir. Kendi sisteminizde her zaman kontrol edin.

PHP

$secret = getenv('BRANTIAL_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$expected = 'sha256='.hash_hmac('sha256', $body, $secret);
$received = $_SERVER['HTTP_X_BRANTIAL_SIGNATURE'] ?? '';

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);

Node.js

import crypto from 'node:crypto';

export function isFromBrantial(rawBody, signature, secret) {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return (
    typeof signature === 'string' &&
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  );
}

Express’te req.body ham bayt olsun diye gövdeyi express.raw({ type: 'application/json' }) ile okuyun ve req.get('X-Brantial-Signature') değerini verin.

Python

import hashlib
import hmac


def is_from_brantial(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

Flask’ta request.get_data() ve request.headers.get("X-Brantial-Signature") değerlerini verin.

Anahtarı değiştirme. Kartta Yeni anahtar’a tıklayın. Eski anahtar hemen çalışmaz olur, bu yüzden sisteminizi hemen ardından güncelleyin.

Gönderim ve yeniden denemeler

• 10 saniye içinde herhangi bir 2xx durum koduyla yanıt verin. Brantial yönlendirmeleri izlemez.
• Adresiniz zaman aşımına uğrarsa, 5xx ile yanıt verirse ya da 429 ile yavaşlamasını isterse Brantial yeniden dener: 1, 5, 15 ve 30 dakika sonra, toplamda en fazla beş deneme.
• Adresiniz 404 veya 410 yanıtı verirse Brantial webhook’un kaldırıldığını kabul eder ve göndermeyi bırakır. Devam etmek için yeniden bağlayın.
• Uzun süren işi yanıt verdikten sonra yapın, önce değil; böylece istek zaman aşımına uğramaz.

Sorun giderme

“Herkese açık bir HTTPS adresi kullanın”

Adresi aracınızdan yeniden kopyalayın. https:// ile başlamalı ve yerel ya da özel bir ağı göstermemeli.

“Adres deneme olayını kabul etmedi”

Parantez içindeki sayı, adresinizin verdiği durum kodudur. Genellikle iş akışı kapalıdır: Zap’i, senaryoyu ya da n8n iş akışını açıp yeniden bağlayın. n8n’de Production URL’yi kopyaladığınızdan emin olun.

“Adres artık var olmadığını bildirdi”

Hook, senaryo ya da iş akışı silinmiş veya kapatılmış. Yeniden açın ya da yenisini oluşturup yeni adresle bağlayın.

“Webhook artık olay kabul etmiyor”

Bağlandıktan sonra adresiniz 404 veya 410 yanıtı verdi, bu yüzden Brantial göndermeyi bıraktı. İş akışını düzeltip yeniden bağlayın.

“Son mesaj iletilemedi”

Bir olay tüm yeniden denemelerden sonra ulaşmadı. Test gönder çalışıyorsa sonraki olay her zamanki gibi gider.

İmza kontrolüm tutmuyor

• Çözülüp yeniden kodlanmış bir kopyayı değil, ham gövdeyi kontrol edin.
• Güncel anahtarı kullandığınızdan emin olun. Yeni anahtar’dan sonra eskisi tutmaz.
• sha256= önekiyle birlikte başlık değerinin tamamını karşılaştırın.

Bağlantıyı kesme

Webhook kartında Bağlantıyı kes’e tıklayın. Brantial adrese olay göndermeyi bırakır.