Webhook

Webhook, bir sistemde gerçekleşen bir olayın ardından, belirlenen bir URL'ye otomatik olarak HTTP isteği gönderilmesiyle başka bir sistemi bilgilendiren bir mekanizmadır.

Webhook URL

Webhook'lar, belirli bir URL üzerinden gelen POST istekleri ile kabul edilir. Örneğin, webhook URL'iniz şu şekilde olabilir:

https://example.com/webhooks/receive

Bu URL, Macellan SuperApp'te belirli olaylar tetiklendiğinde sisteminize veri göndermek için kullanılacaktır.

Webhook Request Formatı

Macellan SuperApp webhook isteklerini (request body) aşağıdaki formatta göndermektedir.

{
    "event": "payment_complete",
    "user": {
        "id": 1,
        "uuid": "a08a39ed-78c5-43dc-ae5c-161e50a634fd",
        "region": "TR",
        "locale": "tr",
        "first_name": "Macellan",
        "last_name": "Superapp",
        "full_name": "Macellan SuperApp",
        "email": "[email protected]",
        "phone": 905231113344,
        "details": {
          "subscribe_sms": false,
          "subscribe_email": false,
          "gender": "male",
          "id_number": 11111111111
        }
    },
    "waas_user_mapping": null,
    "data": {}
}

Webhook İmza Doğrulaması

Tarafımıza bildirdiğiniz webhook URL'inizin güvenliğini sağlamak için, gelen isteğin gerçekten Macellan SuperApp tarafından gönderildiğini doğrulamanız gerekir. Macellan SuperApp, webhook isteklerinde Signature header'ında SHA-256 ile HMAC'lenmiş bir değer gönderir.

Bu değer, request body'nin bize ilettiğiniz Secret Key ile imzalanmasıyla elde edilir.

Örnek request doğrulaması:

function isValidSignature(string $signature, string $requestBody): bool
{
    $secretKey = 'yIfTzdROH4BRtqJs';

    $computedSignature = hash_hmac('sha256', $requestBody, $secretKey);

    return hash_equals($computedSignature, $signature);
}

import * as crypto from 'crypto';

function isValidSignature(signature: string, requestBody: string): boolean {
    const secretKey = 'yIfTzdROH4BRtqJs';

    const computedSignature = crypto
        .createHmac('sha256', secretKey)
        .update(requestBody, 'utf8')
        .digest('hex');

    return crypto.timingSafeEqual(
        Buffer.from(computedSignature),
        Buffer.from(signature)
    );
}

Webhook Başarı ve Başarısız Durumları

Macellan SuperApp, webhook isteği işlendiğinde sisteminizin 200 HTTP durumu döndürmesini bekler.

200 dönülmezse aynı istek en fazla 3 kez daha yeniden gönderilir.