Echovado Giriş yap
Geliştiriciler

API, webhook'lar ve MCP

Echovado takip verilerinizi ajansınızın zaten kullandığı araçlara aktarın. Sürüm 1, salt okunur, Agency planına dahil.

Genel bakış

Echovado, ajanslara takip verilerini panel dışında kullanmanın beş yolunu sunar. Hepsi aynı verileri okur ve aynı sürümlendirilmiş sözleşmeye uyar; böylece birinde gördüğünüz, diğerlerindekiyle eşleşir.

  • REST API: siteleri, puanları, tespitleri, yapay zeka yanıtlarını, puan geçmişini, trendleri ve değişiklikleri bir CRM'e, veri ambarına veya raporlama aracına aktarın.
  • Webhook'lar: bir tarama tamamlandığı ya da yeni yapay zeka yanıtları geldiği anda imzalı bir JSON olayı alın; hiçbir sistemin sürekli sorgu göndermesi gerekmez.
  • MCP sunucusu: Claude, ChatGPT, Cursor veya herhangi bir Model Context Protocol istemcisini bağlayın ve sitelerinizi günlük dilde sorun.
  • Looker Studio: Echovado bağlayıcısıyla puanlar, sorunlar ve yapay zeka görünürlüğü üzerine müşteri raporları oluşturun.
  • Notion: sitelerinizi, sorunları ve yapay zeka yanıtlarını içeren bir Notion sayfasını kod yazmadan güncel tutun.

Adım adım anlatım mı tercih edersiniz? Entegrasyon rehberleri her birinin kurulumunu adım adım gösterir: Notion, Looker Studio, Slack, Discord, Zapier ve Make, REST API ve MCP.

API, webhook'lar, Looker Studio ve Notion Agency planına dahildir. MCP sunucusu Founders & Makers ve üzeri planlarda yer alır: Founders & Makers ve Growth'ta salt okunurdur, Agency'de ise eylem gerçekleştiren araçlar da sunar. Hesap sahibi, anahtarları ve webhook'ları Entegrasyonlar sayfasında yönetir.

Kimlik doğrulama

Entegrasyonlar sayfasında bir anahtar oluşturun. Anahtarın tamamı bir kez gösterilir; biz yalnızca hash değerini saklarız. Anahtarı her istekle birlikte gönderin:

curl https://api.echovado.com/api/v1/sites \
  -H "Authorization: Bearer ecv_YOUR_KEY"

Anahtarlar salt okunurdur ve çalışma alanınızla sınırlıdır: bir anahtar yalnızca onu oluşturan hesaptaki siteleri görür. Entegrasyonlar sayfasında bir anahtarı iptal ettiğinizde anahtar hemen çalışmayı durdurur. Hesap Agency planından çıkarsa, plana geri dönene kadar anahtarları çalışmaz.

İstekler ve limitler

  • Temel URL: https://api.echovado.com/api/v1. GET /api/v1 uç noktaların listesini döndürür.
  • Tüm uç noktalar GET kullanır ve JSON döndürür: { "data": …, "api_version": "v1" }. Sayfalanan listeler ayrıca next_cursor döndürür.
  • Zaman damgaları UTC'de, ISO 8601 biçimindedir. Puanlar 0 ile 100 arasındadır.
  • İstek limiti: anahtar başına dakikada 120 istek. Bu sınırın üzerinde retryAfterSeconds ile birlikte 429 alırsınız.
  • Yolda {site} geçen her yerde site id'sini veya alan adını kullanabilirsiniz, ör. /sites/example.com.

Uç noktalar

GET /account

Planınız, limitleriniz ve kullanımınız.

GET /sites

Takip edilen her site, son puanı ve açık sorunlarıyla birlikte.

{
  "data": [{
    "id": "k3Jd9x2Lq",
    "domain": "example.com",
    "brand_name": "Example",
    "status": "active",
    "created_at": "2026-09-01T10:00:00.000Z",
    "next_scan_at": "2026-10-12T10:00:00.000Z",
    "last_checked_at": "2026-10-05T10:00:00.000Z",
    "score": { "overall": 92, "seo": 95, "geo": 88, "aeo": 90, "aio": 94 },
    "issues": { "critical": 0, "warnings": 2 },
    "regressions_last_7_days": 0,
    "report_url": "https://echovado.com/r/…",
    "app_url": "https://echovado.com/app/?site=k3Jd9x2Lq"
  }],
  "api_version": "v1"
}

GET /sites/{site}

Yukarıdakilerin tümüne ek olarak ai_visibility (kontrol edilen yanıtlar, kaçında adınızın geçtiği, kaçında sitenizin kaynak gösterildiği, takip edilen markalar arasındaki sıranız, ton), takip edilen her marka için share_of_voice, asistanların kaynak gösterdiği top_sources, competitors, questions ve engines.

GET /sites/{site}/findings?status=fail,warn

Son taramanın kontrolleri, kanıt ve düzeltmeyle birlikte (summary, where ve varsa yapıştırmaya hazır code). status verilmezse tüm kontroller döndürülür.

GET /sites/{site}/tasks

Son taramadaki açık sorunlar, bir AI kodlama ajanı (Claude Code, Cursor veya benzeri) için Markdown görevler olarak: bağlam, adımlar, kod, her yer tutucunun sitenin kendisinden nasıl doldurulacağı, görevin ne zaman tamamlanmış sayılacağı ve nelere dokunulmayacağı. { "data": { "markdown": "…", "tasks": 5 } } döndürür. Parametreler: finding (tek bir görev için /findings içinden bir kontrol id'si) ve lang (en, tr, es, de veya fr). Geçen bir kontrol 404 NO_TASK döndürür.

GET /sites/{site}/answers

Kayıtlı yapay zeka yanıtları, en yeniden başlayarak. Her yanıtta soru, asistan (engine), markanızın anılıp anılmadığı (named) ve kaynak gösterilip gösterilmediği (cited), sırası (rank), tonu (sentiment), yanıttaki takip edilen her marka ve yanıtın kaynak gösterdiği kaynaklar yer alır.

Parametreler: engine, question_id, since (ISO tarih), limit (1–500, varsayılan 100), cursor, yanıtın tam metni için include_answer=true. next_cursor null değilse, sonraki sayfayı almak için bu değeri cursor olarak gönderin.

GET /sites/{site}/history

Her taramadan sonraki puan, en eskiden başlayarak (limit en fazla 200).

GET /sites/{site}/trends

Grafikler ve raporlar için day, week (pazartesi) veya month (UTC) bazında gruplanmış zaman serileri. Parametreler: from ve to (YYYY-MM-DD, sınırlar dahil; varsayılan son 90 gün, en fazla iki yıl), bucket (varsayılanı aralığa bağlıdır). Yanıtta periods (dönem başlangıç tarihleri), series (her metrik için periods ile hizalı bir dizi; veri olmayan yerlerde null), her seriyi açıklayan bir catalog (unit: score, pct, count veya rank; better: up veya down) ve aralıktaki changes yer alır.

Seriler: score.overall, score.seo, score.geo, score.aeo, score.aio (her dönemdeki son tarama), issues.fail, issues.warn, ai.visibility, ai.cited, ai.positive, ai.negative (yüzdeler), ai.position (anıldığında ortalama sıra), ai.answers, engine.<assistant> ve intent.<intent> (görünürlük yüzdesi) ve brand.<competitor domain> (o rakibi anan yanıtların payı).

GET /sites/{site}/changes

Taramalar arasında ne değişti: new (yeni sorunlar), worse (kötüleşenler) ve better (düzeltilenler). Parametreler: since, limit.

Hatalar

Hatalar HTTP durum kodlarını ve bir JSON gövdesini kullanır: { "error": "NOT_FOUND", "message": "…" }.

  • 401 eksik, geçersiz veya iptal edilmiş anahtar
  • 403 API_NOT_IN_PLAN çalışma alanı Agency planında değil
  • 404 site bu çalışma alanında değil
  • 405 API salt okunurdur
  • 429 istek limiti aşıldı

Webhook'lar

Entegrasyonlar sayfasında bir https adresi ekleyin ve alınacak olayları seçin. Her olay, JSON gövdeli bir POST isteği olarak gönderilir:

{
  "id": "evt_4Hh2…",
  "type": "scan.completed",
  "api_version": "v1",
  "created_at": "2026-10-05T10:00:00.000Z",
  "data": {
    "site": { "id": "k3Jd9x2Lq", "domain": "example.com", "app_url": "…" },
    "audit_id": "…",
    "checked_at": "2026-10-05T10:00:00.000Z",
    "score": { "overall": 92, "seo": 95, "geo": 88, "aeo": 90, "aio": 94 },
    "issues": { "critical": 0, "warnings": 2 },
    "changes": [{ "finding_id": "seo-title", "kind": "worse", "from": "pass", "to": "warn", "title": "Title tag is too long", "at": "…" }],
    "report_url": "https://echovado.com/r/…"
  }
}

Olaylar

  • score.dropped: genel puan en az webhook'un eşiği kadar düştü (varsayılan %10, webhook başına %1–90). Önceki ve yeni puan, puan ve yüzde olarak düşüş ve her kategorinin değişimi.
  • visibility.lost: bir yapay zeka asistanı, takip edilen bir soruya verdiği bir önceki yanıtta markanızı anmıştı ve artık anmıyor. Asistanı, soruyu ve asistanın yerine önerdiği rakipleri içeren named_instead alanını içerir.
  • visibility.gained: bir asistan daha önce anmadığı markanızı artık anıyor; sırasıyla birlikte.
  • scan.completed: bir tarama tamamlandı (günlük, manuel veya yeniden kontrol). Puanlar, sorun sayıları ve değişenler.
  • answers.updated: takip edilen bir soru için yeni yapay zeka yanıtları; asistan başına bir kayıt, /answers ile aynı biçimde.
  • site.created ve site.deleted.

Bir ping olayı almak için Entegrasyonlar sayfasındaki Test gönder düğmesini kullanın.

Slack, Discord, Asana, ClickUp

Her webhook'un bir mesaj biçimi vardır. Bir Slack veya Discord incoming webhook adresi yapıştırın; Echovado, hesabın dilinde, bağlantılı ve okunaklı tek satırlık bir uyarı gönderir (Slack ve Discord adresleri otomatik olarak algılanır). Asana, ClickUp, Trello, HubSpot ve diğerleri için Zapier, Make veya n8n ile JSON biçimini kullanın: bir "Catch webhook" tetikleyicisi ve ardından bir "Create task" adımı, her score.dropped veya visibility.lost olayını bir göreve dönüştürür. Her gönderim Echovado-Signature başlığını taşır; Slack ve Discord bu başlığı yok sayar.

İmzayı doğrulama

Her istek Echovado-Event, Echovado-Delivery ve Echovado-Signature: t=<unix seconds>,v1=<hex> başlıklarını taşır. İmza, webhook'unuzun imzalama anahtarıyla t + "." + raw body üzerinden hesaplanan bir HMAC-SHA256 değeridir. Karşılaştırmayı sabit sürede (constant time) yapın ve eski zaman damgalarını reddedin:

// Node.js
import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
# Python
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Yeniden denemeler

10 saniye içinde herhangi bir 2xx durum koduyla yanıt verin. Diğer tüm yanıtlarda gönderim yaklaşık 5 dakika, 30 dakika, 2 saat, 6 saat ve 24 saat sonra yeniden denenir. Art arda 25 başarısız gönderimden sonra webhook duraklatılır; Entegrasyonlar sayfasından yeniden açın. Daha önce işlediğiniz bir olayı yok saymak için id değerini kullanın.

MCP sunucusu

MCP uç noktası https://api.echovado.com/mcp adresidir (Streamable HTTP). API uç noktalarını salt okunur araçlar olarak sunar: list_sites, get_site, get_findings, get_tasks, get_ai_answers, get_score_history, get_trends, get_changes. Agency planında sunucu, panelle aynı sınırlara tabi dört eylem aracı daha sunar: add_question (yeni bir soruyu takibe alır; her asistan soruyu hemen yanıtlar), start_scan (bir siteyi hemen tarar; planın günlük manuel tarama hakkından düşülür), mark_task_applied (görevi get_tasks çıktısındaki adıyla iletin; sonraki taramalar öncesini ve sonrasını gösterir) ve add_competitor. Founders & Makers ve Growth planlarında bu araçlar listelenmez.

Başlık kabul eden istemciler (Claude Code, Cursor ve diğerleri):

{
  "mcpServers": {
    "echovado": {
      "url": "https://api.echovado.com/mcp",
      "headers": { "Authorization": "Bearer ecv_YOUR_KEY" }
    }
  }
}

Claude Code: claude mcp add --transport http echovado https://api.echovado.com/mcp --header "Authorization: Bearer ecv_YOUR_KEY"

Yalnızca URL kabul eden istemciler https://api.echovado.com/mcp/ecv_YOUR_KEY adresini kullanabilir. Bu URL'yi bir parola gibi koruyun ve tek başına iptal edebilmek için ona ayrı bir anahtar kullanın.

Örnek sorular: “Bu hafta müşterilerimin hangi siteleri puan kaybetti?”, “ChatGPT example.com yerine kimi öneriyor?”, “example.com sitesindeki kritik sorunları her birinin düzeltmesiyle birlikte listele.”

Looker Studio (Data Studio)

Looker Studio için Echovado bağlayıcısı aynı v1 API'yi okur. Entegrasyonlar sayfasında bir anahtar oluşturun, Looker Studio'da bağla seçeneğini seçin, erişime izin verin ve anahtarı yapıştırın. Veriler rapor açıldığında okunur ve veri kaynağının veri güncelliği (Data freshness) süresi boyunca tutulur (varsayılan 12 saat; daha hızlı güncellemeler için 15 dakika veya 1 saat seçin). Google, 2026'da Looker Studio'nun adını Data Studio olarak değiştirdi; aynı üründür.

Her veri kaynağı için bir tablo seçin ve tek bir siteye veya tüm sitelere göre filtreleyin. Veri kaynaklarını bir raporda Site alanıyla birleştirin. Her tablo mantıklı bir varsayılan grafikle açılır.

  • Score history (varsayılan: zaman içinde GEO puanı): tarama başına bir satır; Scan date, Site, Report ve tüm puanlar ile sorun sayıları. Raporun tarih aralığına uyar.
  • AI visibility vs competitors (varsayılan: markaya göre Times named): her yapay zeka yanıtındaki takip edilen her marka için bir satır; Asked on, Site, Brand, Own brand, Assistant, Question, Intent ile Times named, Times cited ve Rank metrikleri. Rakiplerle karşılaştırmak için Brand'e göre zaman içinde grafiğe dökün.
  • Issue trend by category (varsayılan: zaman içinde kritik sorunlar): tarama ve kategori (SEO, GEO, AEO, AIO) başına bir satır; Critical issues, Warnings, Open issues ve kategori puanı.
  • Sites: Site, Brand name, Last checked, Report, Score, SEO/GEO/AEO/AIO score, Critical issues, Warnings, AI answers checked, AI answers naming the brand, AI named rate, AI rank among tracked brands.
  • Open issues: Site, Issue, Status, Category, Impact, Evidence, How to fix, Where, Check ID ve bir Issues sayacı.
  • AI answers: yanıt başına bir satır; Asked on, Site, Question, Intent, Assistant, Named, Cited as source, Sentiment, Brands named ile Answers, Answers naming the brand, Answers citing the site ve Rank when named metrikleri. Raporun tarih aralığına uyar.

İyi bir başlangıç: Score history tablosundan Score zaman serisi ve AI answers tablosundan Assistant'a göre Answers naming the brand ÷ Answers tablosu.

Notion

Kod gerekmez. Entegrasyonlar sayfasında Notion'ı bağla seçeneğini seçin. Notion'ın onay ekranında ya AI Visibility Dashboard şablonunu çoğaltın (tek tık, başka bir seçim gerekmez) ya da bir sayfa paylaşıp ardından o sayfayı seçin. Her site için bir özet ve sayfa içinde gösterilen üç veritabanı bulunan, markanıza özel bir panel sayfası elde edersiniz; sayfa her taramadan ve her yeni yapay zeka yanıtından sonra güncel tutulur (en geç yaklaşık bir saat sonra ya da Şimdi senkronize et ile hemen):

  • Sites: site başına bir satır; genel puan ile SEO, GEO, AEO ve AIO puanları, kritik sorunlar ve uyarılar, yapay zeka yanıtlarının sizi ne sıklıkla andığı, takip edilen markalar arasındaki sıranız, tarihler ve rapor ile panel bağlantıları.
  • Issues: durum, kategori, etki, kanıt ve düzeltme yöntemiyle birlikte açık tespitler. Düzeltilen sorunlar silinmez, Resolved olarak işaretlenir.
  • AI answers (yapay zeka soru kaydı): son 30 günden itibaren yanıt başına bir satır; soru, niyeti, asistan, adınızın geçip geçmediği, sıra, kaynak gösterilme, ton, anılan markalar ve kaynaklar.

Satırlar yerinde güncellenir, hiçbir zaman yinelenmez. Kendi sütunlarınızı ve görünümlerinizi ekleyebilirsiniz; bizim sütunlarımız her senkronizasyonda üzerine yazılır. Sonradan eklediğimiz yeni sütunlar mevcut veritabanlarınızda otomatik olarak görünür. Bağlantıyı kesmek güncellemeleri durdurur ve sayfaları Notion'da bırakır.

Arama niyeti ve ton

Takip edilen her soru bir niyet etiketi alır: research, comparison, purchase veya brand. Etiket, küçük bir dil modeli tarafından bir kez belirlenir (yedek olarak anahtar kelime eşleştirmesi kullanılır). Bir yanıt markanızı andığında yanıtın tonu positive, neutral veya negative olarak etiketlenir. Her ikisi de API'de (questions[].intent, answers[].question.intent, answers[].sentiment, ai_visibility.by_intent), Notion'da ve Looker Studio'da yer alır; panelde yanıtlar bunlara göre filtrelenebilir.

Sürümlendirme

Bu, sürüm 1'dir. v1 içinde yalnızca ekleme yaparız: yeni uç noktalar, yeni alanlar ve yeni olay türleri. Alanları kaldırmaz veya yeniden adlandırmaz, anlamlarını ya da türlerini değiştirmeyiz. Tanımadığınız alanları yok sayarsanız, biz özellik ekledikçe entegrasyonunuz çalışmaya devam eder. Geriye dönük uyumluluğu bozan bir değişiklik gerekirse v1'in yanında /api/v2 olarak yayınlanır ve v1, e-postayla duyurulan bir geçiş süresi boyunca çalışmaya devam eder.

Değişiklik günlüğü

  • 2026-10: v1 yayınlandı: REST API, webhook'lar (scan.completed, answers.updated, site.created, site.deleted), MCP sunucusu ve Notion senkronizasyonu.
  • 2026-10: uyarılar (score.dropped, visibility.lost, visibility.gained), Slack ve Discord biçimleri, Notion panel şablonu, Looker Studio rakip ve kategori tabloları, soru niyeti.
  • 2026-10: GET /sites/{site}/tasks ve get_tasks MCP aracı: açık sorunlar, AI kodlama ajanları için Markdown görevler olarak.