Pingolab API dokümantasyonu

Kimlik doğrulama

Panelde bir anahtar oluştur (Ayarlar → API anahtarları) ve Bearer token olarak gönder. Anahtarlar bir kez gösterilir ve özetleri saklanır. Üç türü var:

Full Read / Write

Tam erişim — okuma ve yazma.

Read-Only GET Only

Salt okunur — tüm GET uç noktaları.

Monitor Widget Safe

Tek monitör — sadece bir monitörü okur; herkese açık widget'lar için güvenli.

HTTP Header

Authorization: Bearer pl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Yanıt formatı

snake_case anahtarlı JSON. Zamanlar UTC ve ISO 8601; kimlikler herkese açık ULID'lerdir. Tekil kaynaklar ve listeler data içinde; sayfalama için meta ve links bulunur.

Envelope JSON

{
    "data": {
        "id": "01J8Z3ABCD1234EXAMPLE01",
        "type": "http",
        "name": "Production Website",
        "url": "https://example.com",
        "status": "up",
        "interval_seconds": 60,
        "created_at": "2026-09-28T10:00:00+00:00"
    },
    "meta": {
        "next_cursor": "eyJpZCI6IjAxSjha..."
    },
    "links": {
        "next": "https://panel.pingolab.net/api/v1/monitors?cursor=eyJpZCI6IjAxSjha..."
    }
}

Hatalar

Hatalar her zaman aynı yapıdadır. code sabittir ve dokümante edilmiştir; message Accept-Language başlığına göre (tr veya en) gelir.

Error Payload

{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "details": {
            "url": [
                "The url field must be a valid URL."
            ]
        }
    }
}

Hata Kodu	HTTP	Açıklama
unauthenticated	401	Eksik veya geçersiz Bearer API anahtarı
forbidden	403	Bu kaynak için yetersiz anahtar izinleri
not_found	404	İstenen kaynak veya uç nokta bulunamadı
method_not_allowed	405	Bu uç noktada HTTP metodu desteklenmiyor
idempotency_in_progress	409	Bu Idempotency-Key ile aynı istek şu anda işleniyor
validation_failed	422	İstek gövdesi doğrulama kurallarını geçemedi
idempotency_mismatch	422	Idempotency-Key daha önce farklı bir veriyle kullanılmış
rate_limited	429	İstek sınırı aşıldı (60 istek/dk). Retry-After başlığına bakın
server_error	500	Sunucu hatası oluştu. Pingolab ekibine otomatik bildirildi

Sayfalama

Listeler cursor tabanlı sayfalama kullanır: ?limit= gönder (en fazla 100, varsayılan 25) ve links.next'i ya da meta.next_cursor'ı ?cursor= ile takip et.

?limit=25&cursor=…

İstek sınırları

Varsayılan olarak anahtar başına dakikada 60 istek. Her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset bulunur; sınır aşılınca Retry-After ile 429 döner.

X-RateLimit-Limit: 60

Idempotency

POST isteklerinde güvenle tekrar denemek için Idempotency-Key başlığı gönder: ilk yanıt 24 saat saklanır ve tekrar oynatılır (Idempotent-Replayed: true). Aynı anahtar farklı gövdeyle kullanılırsa idempotency_mismatch döner.

Idempotency-Key: <uuid>

Kod örnekleri

Popüler programlama dilleriyle REST API istekleri gönderin. Tüm çağrılarda Authorization başlığı gereklidir.

# 1. Monitörleri Listele (GET)
curl https://panel.pingolab.net/api/v1/monitors \
  -H "Authorization: Bearer pl_your_key" \
  -H "Accept: application/json"

# 2. Yeni HTTP Monitör Oluştur (POST)
curl -X POST https://panel.pingolab.net/api/v1/monitors \
  -H "Authorization: Bearer pl_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c98a2-d4b3-4f9e-8c67-1234567890ab" \
  -d '{
    "type": "http",
    "name": "Canlı Web Sitesi",
    "url": "https://example.com",
    "interval_seconds": 60
  }'

// JavaScript (Fetch / Node.js 18+)
const res = await fetch('https://panel.pingolab.net/api/v1/monitors', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pl_your_key',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    type: 'http',
    name: 'Canlı Web Sitesi',
    url: 'https://example.com',
    interval_seconds: 60,
  }),
});

const { data } = await res.json();
console.log('Monitör oluşturuldu:', data.id);

// PHP (Laravel Http İstemcisi)
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

$response = Http::withToken('pl_your_key')
    ->acceptJson()
    ->withHeaders([
        'Idempotency-Key' => (string) Str::uuid(),
    ])
    ->post('https://panel.pingolab.net/api/v1/monitors', [
        'type' => 'http',
        'name' => 'Canlı Web Sitesi',
        'url' => 'https://example.com',
        'interval_seconds' => 60,
    ]);

$monitor = $response->json('data');

# Python (requests)
import uuid
import requests

response = requests.post(
    'https://panel.pingolab.net/api/v1/monitors',
    headers={
        'Authorization': 'Bearer pl_your_key',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
        'type': 'http',
        'name': 'Canlı Web Sitesi',
        'url': 'https://example.com',
        'interval_seconds': 60,
    },
)

monitor = response.json()['data']
print(f"Monitör ID: {monitor['id']}")

Webhook'lar

Webhook bildirim kanalları her olay için bir JSON POST alır. Her istek, kanalın imza anahtarıyla "timestamp.body" üzerinden HMAC-SHA256 ile imzalanır. Geri çekilmeli olarak en fazla 3 kez yeniden deneriz.

Olaylar:

down up ssl_expiring ssl_expired heartbeat_missed reminder flapping_summary test

Sample Webhook Delivery

X-Pingolab-Event: down
X-Pingolab-Timestamp: 1790335924
X-Pingolab-Signature: sha256=a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef0

{
    "event": "down",
    "occurred_at": "2026-09-28T12:00:00+00:00",
    "monitor": {
        "id": "01J8Z3ABCD1234EXAMPLE01",
        "name": "Production Website",
        "type": "http",
        "url": "https://example.com",
        "status": "down"
    },
    "incident": {
        "id": "01J8Z4XYZ9876INCIDENT01",
        "started_at": "2026-09-28T11:59:00+00:00",
        "resolved_at": null,
        "duration_seconds": null,
        "error_type": "timeout",
        "error_message": "Connection timed out after 10000ms"
    },
    "details": {},
    "links": {
        "monitor": "https://panel.pingolab.net/monitors/01J8Z3ABCD1234EXAMPLE01"
    }
}

İmzayı doğrulama (sabit zamanlı)

Gelen isteklerin Pingolab tarafından gönderildiğini ve gövdenin değiştirilmediğini doğrulamak için imza kontrolü yapın. Sabit zamanlı (constant-time) karşılaştırma kullanmanız önerilir.

// PHP (HMAC-SHA256 Sabit Zamanlı İmza Doğrulama)
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_PINGOLAB_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_PINGOLAB_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

// Yeniden oynatma saldırı koruması (5 dakika tolerans)
if (abs(time() - (int) $timestamp) > 300 || ! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Geçersiz webhook imzası');
}

// Olayı güvenle işle
$event = json_decode($payload, true);

// Node.js (Kriptografik Sabit Zamanlı Doğrulama)
import crypto from 'node:crypto';

function verifyWebhook(rawBody, timestamp, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // Zaman damgası tazeliği (5 dakika tolerans)
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  
  return fresh && crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

# Python (HMAC-SHA256 Sabit Zamanlı Doğrulama)
import hmac
import hashlib
import time

def verify_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    # Zaman damgasını doğrula (5 dakika içinde)
    if abs(time.time() - int(timestamp)) > 300:
        return False
        
    expected = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        f'{timestamp}.'.encode('utf-8') + raw_body,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected, signature)

Pingolab REST API