API & Webhook Dokümantasyonu

Alertalk'ı monitoring sistemlerinizle entegre edin. Güçlü API ve webhook desteği ile otomatik sesli uyarı sistemi kurun.

Başlangıç

Alertalk API ve Webhook sistemi, monitoring platformlarınızdan gelen uyarıları otomatik olarak sesli aramaya dönüştürür. Sistem downtime'ları, güvenlik olayları ve kritik alarmlar için anında telefon bildirimi alabilirsiniz.

Özellikler

  • Sesli Arama API: Programatik olarak sesli uyarı tetikleme
  • Webhook Receiver: Monitoring sistemlerinden otomatik bildirim alma
  • Çoklu Telefon Desteği: Birden fazla kişiye aynı anda arama
  • Arama Kredisi Sistemi: Kullanım tabanlı ücretlendirme
  • Güvenli Entegrasyon: API key ve HMAC imzalama
Not: API ve Webhook özelliklerini kullanabilmek için Starter veya üzeri bir planınızın olması gerekiyor. Free plan bu özellikleri desteklememektedir.

Kimlik Doğrulama

API Anahtarları

Panel'den API Anahtarları bölümünden API Key, API Secret ve Webhook Key'inizi oluşturabilirsiniz.

API Key: 1a2b3c4d5e6f7g8h
API Secret: 9i10j11k12l13m14n15o16p17q18r19s20t21u22v23w24x25y26z27a28b29c30d31e32f
Webhook Key: abc123def456

API Authentication

API çağrıları için API Key ve API Secret kullanılır. Güvenlik için timestamp tabanlı HMAC imzalama da desteklenir.

Webhook Authentication

Webhook endpoint'i için sadece Webhook Key yeterlidir. URL'e query parameter olarak eklenir.

API Referansı

POST /api/call

Sesli Arama Tetikleme

Belirtilen telefon numarasına özel mesajla sesli arama başlatır.

Request Parameters
Parametre Tip Zorunlu Açıklama
api_key string Evet Panel'den aldığınız API anahtarı
api_secret string Evet Panel'den aldığınız API secret
phone_number string Evet Aranacak telefon numarası (5xxxxxxxxx)
error_message string Evet Sesli uyarıda söylenecek mesaj
Örnek Request
curl -X POST https://tr.alertalk.net/api/call \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "1a2b3c4d5e6f7g8h",
    "api_secret": "9i10j11k12l...",
    "phone_number": "5551234567",
    "error_message": "PRTG uyarısı: Web sunucusu erişilemez durumda. Lütfen kontrol ediniz."
  }'
Başarılı Response
{
  "status": "success",
  "message": "Call queued"
}
Hata Response'ları
Eksik Parametre (400)
{
  "status": "error",
  "message": "Missing fields"
}
Geçersiz API Bilgileri (403)
{
  "status": "error",
  "message": "Invalid API credentials"
}
Yetersiz Kredi (402)
{
  "status": "error",
  "message": "Insufficient call credit"
}

Webhook Referansı

POST /webhook/receive?key=YOUR_WEBHOOK_KEY

Webhook Endpoint

Monitoring sistemlerinizden otomatik uyarı almak için kullanın. Birden fazla telefon numarasına aynı anda arama yapabilir.

URL Parametreleri
Parametre Tip Zorunlu Açıklama
key string Evet Panel'den aldığınız webhook anahtarı
Request Body Parametreleri
Parametre Tip Zorunlu Açıklama
phone_number string Evet Virgülle ayrılmış telefon numaraları
error_message string Evet Sesli uyarıda söylenecek mesaj
Çoklu Telefon: phone_number alanında virgülle ayırarak birden fazla numara gönderebilirsiniz. Örnek: "5551234567,5559876543,5555555555"
Örnek Webhook Call
curl -X POST "https://tr.alertalk.net/webhook/receive?key=dddb8a81081" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "5459281006",
    "error_message": "FortiGate Event: Başarısız giriş denemesi!"
  }'
Başarılı Response
{
  "status": "success",
  "message": "2 call(s) queued"
}
Webhook Content-Type Desteği

Webhook endpoint'i farklı content-type formatlarını destekler:

  • application/json - JSON formatında data
  • application/x-www-form-urlencoded - Form data
  • text/plain - Raw JSON string

Platform Entegrasyonları

Alertalk'ı popüler monitoring ve güvenlik platformlarıyla nasıl entegre edeceğinizi öğrenin:

🖥️ PRTG Network Monitor

PRTG'deki sensor alarm'larını Alertalk webhook'una yönlendirerek otomatik sesli uyarı alın.

Konfigürasyon Rehberi →

📊 Zabbix

Zabbix trigger'larını webhook action ile Alertalk'a gönderip kritik uyarılar için arama yaptırın.

Konfigürasyon Rehberi →

🛡️ FortiGate

FortiGate güvenlik event'lerini webhook ile gönderip anında sesli güvenlik uyarısı alın.

Konfigürasyon Rehberi →

⚙️ Nagios

Nagios host/service check'lerinin CRITICAL durumlarında sesli arama tetikleyin.

Konfigürasyon Rehberi →

☁️ AWS CloudWatch

CloudWatch alarm'larını SNS üzerinden webhook'a yönlendirip cloud altyapı uyarıları alın.

Konfigürasyon Rehberi →

📈 Grafana

Grafana alert rule'larını webhook notification channel ile Alertalk'a bağlayın.

Konfigürasyon Rehberi →

Örnek Kullanımlar

Python Örneği

import requests
import json

def alertalk_call(phone, message):
    url = "https://tr.alertalk.net/api/call"
    
    payload = {
        "api_key": "YOUR_API_KEY",
        "api_secret": "YOUR_API_SECRET", 
        "phone_number": phone,
        "error_message": message
    }
    
    headers = {
        "Content-Type": "application/json"
    }
    
    response = requests.post(url, data=json.dumps(payload), headers=headers)
    
    if response.status_code == 200:
        print("Arama başarıyla tetiklendi")
        return response.json()
    else:
        print(f"Hata: {response.status_code} - {response.text}")
        return None

# Kullanım
result = alertalk_call("5551234567", "Kritik sistem hatası tespit edildi!")
print(result)

PHP Örneği

<?php
function alertalkCall($phone, $message) {
    $url = "https://tr.alertalk.net/api/call";
    
    $data = array(
        'api_key' => 'YOUR_API_KEY',
        'api_secret' => 'YOUR_API_SECRET',
        'phone_number' => $phone,
        'error_message' => $message
    );
    
    $options = array(
        'http' => array(
            'header'  => "Content-type: application/json\r\n",
            'method'  => 'POST',
            'content' => json_encode($data)
        )
    );
    
    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    
    if ($result === FALSE) {
        return false;
    }
    
    return json_decode($result, true);
}

// Kullanım
$response = alertalkCall("5551234567", "PHP'den test uyarısı!");
print_r($response);
?>

PowerShell Örneği (Windows)

function Send-AlertalkCall {
    param(
        [string]$PhoneNumber,
        [string]$Message,
        [string]$ApiKey = "YOUR_API_KEY",
        [string]$ApiSecret = "YOUR_API_SECRET"
    )
    
    $uri = "https://tr.alertalk.net/api/call"
    
    $body = @{
        api_key = $ApiKey
        api_secret = $ApiSecret
        phone_number = $PhoneNumber
        error_message = $Message
    } | ConvertTo-Json
    
    try {
        $response = Invoke-RestMethod -Uri $uri -Method Post -Body $body -ContentType "application/json"
        Write-Host "Arama başarıyla tetiklendi: $($response.message)" -ForegroundColor Green
        return $response
    }
    catch {
        Write-Host "Hata: $($_.Exception.Message)" -ForegroundColor Red
        return $null
    }
}

# Kullanım
Send-AlertalkCall -PhoneNumber "5551234567" -Message "Windows sunucusunda kritik hata!"

FortiGate Webhook Entegrasyonu

FortiGate'den gelen güvenlik event'lerini Alertalk webhook'una yönlendirme:

# FortiGate webhook konfigürasyonu için
# Webhook URL: https://tr.alertalk.net/webhook/receive?key=YOUR_WEBHOOK_KEY
# Method: POST
# Body format:
{
  "phone_number": "5459281006", 
  "error_message": "FortiGate Event: Başarısız giriş denemesi!"
}

Bash/cURL Örneği

#!/bin/bash

# Alertalk API bilgileri
API_KEY="YOUR_API_KEY"
API_SECRET="YOUR_API_SECRET"
WEBHOOK_URL="https://tr.alertalk.net/webhook/receive?key=YOUR_WEBHOOK_KEY"

# Sesli arama fonksiyonu
alertalk_call() {
    local phone="$1"
    local message="$2"
    
    curl -X POST "https://tr.alertalk.net/api/call" \
        -H "Content-Type: application/json" \
        -d "{
            \"api_key\": \"$API_KEY\",
            \"api_secret\": \"$API_SECRET\",
            \"phone_number\": \"$phone\",
            \"error_message\": \"$message\"
        }"
}

# Webhook çağrısı
alertalk_webhook() {
    local phones="$1"  # Virgülle ayrılmış
    local message="$2"
    
    curl -X POST "$WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -d "{
            \"phone_number\": \"$phones\",
            \"error_message\": \"$message\"
        }"
}

# Kullanım örnekleri
alertalk_call "5551234567" "Linux sunucusunda disk dolu!"
alertalk_webhook "5551234567,5559876543" "Kritik sistem uyarısı - hemen kontrol edin!"

Limitler ve Kısıtlamalar

Arama Kredisi Sistemi

Her ağır plan farklı miktarda aylık arama kredisi ile gelir:

Plan Aylık Arama Kredisi API Erişimi Webhook Erişimi
Free 1 arama
Starter 15 arama
Professional 50 arama
Enterprise 100+ arama
Kredi Tükenmesi: Aylık arama krediniz tükendiğinde API ve webhook çağrıları "Insufficient call credit" hatası döndürür. Kredi durumunuzu panel'den takip edebilirsiniz.

Güvenlik Limitleri

  • Rate Limiting: Aynı IP'den dakikada maksimum 60 istek
  • Request Timeout: API çağrıları 30 saniye içinde tamamlanmalı
  • Message Length: error_message maksimum 500 karakter
  • Phone Validation: Telefon numarası 10 haneli ve 5 ile başlamalı

Webhook Özellikleri

  • Timeout: Webhook response 10 saniye içinde dönmeli
  • Retry Policy: Başarısız webhook'lar 3 kez tekrar denenir
  • Max Phones: Tek webhook çağrısında maksimum 10 telefon numarası
  • Content-Type: JSON, form-data ve plain text desteklenir

Sorun Giderme

Yaygın Hatalar

❌ "Invalid API credentials"

  • API Key ve API Secret'ın doğru olduğundan emin olun
  • Panel'den yeni API anahtarları oluşturmayı deneyin
  • JSON formatının doğru olduğunu kontrol edin

❌ "Missing fields"

  • Tüm zorunlu alanların gönderildiğini kontrol edin
  • phone_number ve error_message alanlarının boş olmadığından emin olun
  • Content-Type header'ının "application/json" olduğunu kontrol edin

❌ "Insufficient call credit"

  • Panel'den arama kredisi durumunuzu kontrol edin
  • Planınızı yükseltin veya kredi yenilenmesini bekleyin
  • Aylık kredi döngüsü her ay 1'inde sıfırlanır

❌ "Your plan does not allow API/webhook access"

  • Free plan API/webhook desteklemiyor - Starter'a geçin
  • Abonelik durumunuzu panel'den kontrol edin
  • Ödeme durumunda sorun olup olmadığını kontrol edin

Test Etme

Entegrasyonunuzu test etmek için:

# Test API çağrısı
curl -X POST https://tr.alertalk.net/api/call \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET",
    "phone_number": "YOUR_PHONE_NUMBER",
    "error_message": "Test uyarısı - entegrasyon çalışıyor!"
  }'

# Test Webhook çağrısı  
curl -X POST "https://tr.alertalk.net/webhook/receive?key=YOUR_WEBHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "YOUR_PHONE_NUMBER",
    "error_message": "Webhook test uyarısı!"
  }'

Debug İpuçları

  • Response Kodları: HTTP status kodlarını kontrol edin (200=başarılı, 400=hatalı istek, 403=yetkisiz)
  • Log Kayıtları: Panel'de API çağrı geçmişinizi inceleyebilirsiniz
  • JSON Validation: Gönderdiğiniz JSON'ın geçerli olduğundan emin olun
  • Encoding: Türkçe karakterler için UTF-8 encoding kullanın

Destek

Bu dokümantasyonda bulamadığınız konular için:

  • 📧 E-mail: support@alertalk.net
  • 📞 Telefon: +90 (212) 345 67 89
  • 💬 Canlı Destek: Panel içinden mesaj gönderin
Pro İpucu: Webhook entegrasyonlarınızı test ederken önce manuel API çağrısı yaparak sisteminizin çalıştığından emin olun, sonra webhook'u yapılandırın.