Webhook [beta]

Adisyo Webhook'u Kullanma

Adisyo Webhook ile olayları dinlemeye başlayabilir (subscribe) ve bu olaylar gerçekleştiğinde belirlediğiniz bir URL'nin Adisyo tarafından tetiklenmesini (trigger) sağlayabilirsiniz.

Temel Endpoint Oluşturma

Webhook endpoint'iniz POST isteklerini kabul eden bir HTTP servisi olmalıdır.

1. Basit Endpoint Oluşturun

const express = require('express');
const app = express();
 
// JSON body parsing
app.use(express.json());
 
// Webhook endpoint
app.post('/webhook', (req, res) => {
  console.log('Webhook alındı:', req.body);
  res.status(200).json({ success: true });
});
 
app.listen(3000, () => {
  console.log('Webhook server çalışıyor: http://localhost:3000');
});

2. Endpoint'inizi Dışarıya Açın

Yerel geliştirme için ngrok kullanın:

# ngrok kurulumu
npm install -g ngrok
 
# Sunucunuzu başlatın
node webhook-server.js
 
# Başka terminalde ngrok başlatın
ngrok http 3000

ngrok size şu şekilde bir URL verecek:

https://abc123.ngrok.io

3. Adisyo Panelinde Yapılandırın

  1. Adisyo paneline gidin
  2. Uygulama Mağazası > Webhook bölümüne gidin
  3. Yeni Webhook Oluştur butonuna tıklayın
  4. Aşağıdaki bilgileri girin:
    • Firma Adı: Webhook Adı (maksimum 10 karakter)
    • Servis URL: https://abc123.ngrok.io/webhook
  5. Webhook Oluştur butonuna tıklayın
  6. Oluşturulan API Key'i kopyalayın
⚠️

API Key'i güvenli bir yerde saklayın. Bu anahtar webhook güvenliği için kritiktir.

URL Doğrulama

Adisyo webhook URL'nizi özel bir istek göndererek doğrular:

app.post('/webhook', (req, res) => {
  // URL doğrulama - Adisyo "adisyo" string'i gönderir
  if (req.body === 'adisyo') {
    return res.status(200).send('adisyo');
  }
  
  // Normal webhook işlemi
  console.log('Webhook alındı:', req.body);
  res.status(200).json({ success: true });
});

URL doğrulama sadece webhook oluşturulurken bir kez yapılır. Bu isteği "adisyo" olarak yanıtlamanız gerekir.

Endpoint Gereksinimleri

Webhook endpoint'iniz şu gereksinimleri karşılamalıdır:

GereksinimAçıklama
HTTP YöntemleriPOST isteklerini kabul etmeli, GET isteklerini reddetmeli
Yanıt FormatıBaşarılı: HTTP 200, Hata: HTTP 4xx/5xx
Yanıt SüresiMaksimum 5 saniye
GüvenlikHTTPS kullanın, imza doğrulaması yapın, rate limiting uygulayın

Örnek Endpoint Uygulaması

import express from 'express';
import { createHmac, timingSafeEqual } from 'crypto';
const app = express();
 
app.use(express.json());
 
const API_KEY = process.env.ADISYO_API_KEY;
 
// İmza doğrulama fonksiyonu
function verifySignature(payload, signature, apiKey) {
  const webhookData = JSON.parse(payload);
  const message = `${webhookData.WebhookEventType}|${webhookData.EventTimeUtc}|${apiKey}`;
  const expectedSignature = createHmac('sha256', apiKey)
    .update(message)
    .digest('base64');
  
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
app.post('/webhook', (req, res) => {
  try {
    // URL doğrulama
    if (req.body === 'adisyo') {
      return res.status(200).send('adisyo');
    }
    
    // İmza doğrulama
    const signature = req.headers['x-adisyo-signature'];
    if (!verifySignature(JSON.stringify(req.body), signature, API_KEY)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
    
    // Webhook işle
    console.log('Webhook alındı:', req.body);
    res.status(200).json({ success: true });
    
  } catch (error) {
    console.error('Webhook hatası:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});
 
app.listen(3000);

Sonraki Adımlar

Webhook'unuzu güvenli hale getirmek ve event'leri işlemek için:

Kurye Kullanıcılarıİmza Doğrulama