Genel Bakış
Webhook entegrasyonu, GroMach'tan makale verilerini alıp kendi backend sisteminizde işlemenize olanak tanır. Bir makale yayınladığınızda, GroMach yapılandırdığınız endpoint'e makale içeriğiyle birlikte bir POST isteği gönderir.
Adım 1: Webhook Endpoint'inizi Kurun
Webhook isteklerini almak için sunucunuzda bir HTTPS endpoint'i oluşturun. Endpoint şunları yapmalıdır:
- POST isteklerini kabul etmeli: Tüm webhook verileri POST ile gönderilir
- HTTPS kullanmalı: Güvenlik için yalnızca HTTPS URL'leri desteklenir
- 2xx durum kodu döndürmeli: Alındığını onaylamak için başarı durum kodu döndürün
Adım 2: İmza Doğrulamasını Uygulayın
GroMach, tüm webhook isteklerini HMAC-SHA256 kullanarak imzalar. İsteklerin gerçek olduğundan emin olmak için bu imzayı doğrulamalısınız.
Her istek şu başlıkları içerir:
- x-webhook-signature: İstek gövdesinin HMAC-SHA256 imzası
- x-webhook-timestamp: İsteğin gönderildiği ISO 8601 zaman damgası
- Content-Type: application/json
İşte Node.js'te imza doğrulama örneği:
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const computedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(computedSignature, 'hex')
);
}
// In your endpoint handler:
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
if (!verifySignature(payload, signature, YOUR_SECRET_KEY)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process the webhook...
res.json({ success: true });
});Adım 3: Webhook Payload Formatı
Bir makale yayınlandığında, GroMach aşağıdaki yapıya sahip bir payload gönderir:
{
"event_type": "publish_articles",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"articles": [
{
"id": "article-uuid-123",
"slug": "my-article-slug",
"title": "Article Title",
"excerpt": "Brief description of the article...",
"content_format": "markdown",
"content": "# Full article content in markdown...",
"status": "published",
"published_at": "2024-01-15T10:30:00.000Z",
"author_name": "Admin",
"cover_image": "https://example.com/image.jpg",
"meta_title": "SEO Title",
"meta_description": "SEO meta description",
"tags": ["seo", "marketing"]
}
]
}
}Makale Alanları Referansı
- id: Makale için benzersiz tanımlayıcı
- slug: Makale için URL dostu tanımlayıcı
- title: Makale başlığı
- excerpt: Kısa açıklama veya özet
- content_format: "markdown" veya "html"
- content: Tam makale içeriği
- status: Yayın durumu (draft, published, archived)
- published_at: ISO 8601 yayın zaman damgası
- author_name: Yazar görünen adı
- cover_image: Kapak görselinin URL'si (varsa)
- meta_title: Arama motorları için SEO başlığı
- meta_description: SEO meta açıklaması
- tags: Etiket dizileri
Adım 4: GroMach'ta Yapılandırın
GroMach entegrasyonlar sayfasında, aşağıdaki bilgileri doldurun:
- İsim (İsteğe Bağlı): Bu webhook'u tanımlamak için kolay bir isim
- Webhook URL: HTTPS endpoint URL'niz (örn., https://your-site.com/api/webhook)
- Gizli Anahtar: İstekleri imzalamak için kullanılan gizli bir dize (bunu güvende tutun!)
- Yayın Durumu: Makalelerin "published" veya "draft" olarak gönderilip gönderilmeyeceğini seçin
Önemli
Gizli Anahtarınızı güvende tutun ve asla istemci tarafı kodunda açığa çıkarmayın. Sunucunuzda güvenli bir şekilde saklamak için ortam değişkenlerini kullanın.
Webhook'unuzu Test Etme
Entegrasyonu oluşturmadan önce, "Bağlantıyı Test Et" butonunu kullanarak webhook bağlantınızı test edebilirsiniz. GroMach, endpoint'inizin düzgün yapılandırıldığını doğrulamak için bir test isteği gönderecektir.
Test Gereksinimleri
Testin geçmesi için, endpoint'iniz şunları yapmalıdır:
- 1. İmzayı doğrulayın:
X-Webhook-Signaturebaşlığını doğrulamak için gizli anahtarı kullanın - 2. Başarı yanıtı döndürün:
{ "success": true }içeren bir JSON yanıtı döndürün
Test payload'u şöyle görünür:
{
"event_type": "test",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"message": "This is a test webhook from Gromach SEO",
"integration_name": "My Webhook"
}
}Test endpoint'inizin isteği nasıl ele alması gerektiğine dair eksiksiz bir örnek:
const crypto = require('crypto');
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
// Step 1: Verify the signature
const computedSignature = crypto
.createHmac('sha256', YOUR_SECRET_KEY)
.update(payload)
.digest('hex');
const isValid = crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(computedSignature, 'hex')
);
if (!isValid) {
return res.status(401).json({
success: false,
error: 'Invalid signature'
});
}
// Step 2: Process based on event type
if (req.body.event_type === 'test') {
// Test connection - just return success
return res.json({ success: true });
}
if (req.body.event_type === 'publish_articles') {
// Process articles...
const articles = req.body.data.articles;
// Save to your database, etc.
return res.json({ success: true });
}
res.json({ success: true });
});İmza doğrulaması neden gereklidir
İmza doğrulaması, webhook isteklerinin gerçekten GroMach'tan geldiğinden ve değiştirilmediğinden emin olur. Bu, endpoint'inizi yetkisiz isteklerden koruyan bir güvenlik en iyi uygulamasıdır.
Sorun Giderme
Bağlantı testi başarısız oluyor
- • Endpoint URL'nizin doğru olduğunu ve HTTPS kullandığını doğrulayın
- • Sunucunuzun internetten erişilebilir olduğundan emin olun
- • Endpoint'inizin 2xx durum kodu döndürdüğünü kontrol edin
İmza doğrulaması başarısız oluyor
- • GroMach'tan aldığınız tam Gizli Anahtarı kullandığınızdan emin olun
- • Ham istek gövdesini hash'lediğinizi, ayrıştırılmış bir nesneyi değil, doğrulayın
- • Zamanlama saldırılarını önlemek için zamanlama güvenli karşılaştırma kullanın
Makaleler görünmüyor
- • Sunucu günlüklerinizi herhangi bir işleme hatası için kontrol edin
- • Makale durumunun beklenen iş akışınızla eşleştiğini doğrulayın
- • Veritabanı işlemlerinizin başarıyla tamamlandığından emin olun