Webhook imza anahtarını nasıl kullanırım, kaybedersem ne olur?

Adım adım

Entegrasyonlar > Webhook / CRM sayfasında Anahtarı yenile’ye tıklayın.
Görünen yeni anahtarı Kopyala ile kopyalayıp sisteminize kaydedin. Ekranda “Yeni anahtar üretir; eski imzalar geçersiz olur ve yeniden doğrulama gerekir.” yazar.
Yeni anahtarı sisteminize girdikten sonra Test gönder’e tıklayın. Test başarılı olunca entegrasyon yeniden Aktif olur.
Geliştiricinize sayfanın altındaki İmza doğrulama bölümünü ya da bu makaleyi iletin.

İmza nasıl doğrulanır?

Her istekte şu biçimde bir başlık gelir:

X-ClinicVi-Signature: t=1767000000,v1=3f9a8c...

t: İsteğin imzalandığı an, Unix zaman damgası (saniye).
v1: İmza anahtarınızla hesaplanan HMAC-SHA256 özeti (küçük harf hex). İmzalanan metin t değeri, bir nokta ve isteğin ham gövdesidir.
Anahtarın tamamını, whsec_ ile başlayan hâliyle kullanın.
Gövdeyi ayrıştırıp yeniden JSON’a çevirmeyin; gelen ham metni kullanın.
t 5 dakikadan eskiyse isteği reddetmenizi öneririz.
Aynı X-ClinicVi-Delivery değeriyle gelen isteği bir kez işleyin. Aynı gönderim nadiren birden fazla gelebilir.

Node.js örneği

import crypto from 'node:crypto';

// rawBody: isteğin ham gövdesi (metin)
// header:  X-ClinicVi-Signature başlığının değeri
// secret:  whsec_ ile başlayan imza anahtarınız
export function isFromClinicVi(rawBody, header, secret) {
  const parts = {};
  for (const item of String(header || '').split(',')) {
    const [key, value] = item.trim().split('=');
    parts[key] = value;
  }
  if (!parts.t || !parts.v1) return false;

  // 5 dakikadan eski istekleri reddedin
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Express kullanıyorsanız bu adres için gövdeyi express.raw({ type: 'application/json' }) ile ham olarak alın ve doğrulamadan önce metne çevirin.

PHP örneği

<?php
// $rawBody = file_get_contents('php://input');
// $header  = $_SERVER['HTTP_X_CLINICVI_SIGNATURE'] ?? '';
function isFromClinicVi(string $rawBody, string $header, string $secret): bool
{
    $parts = [];
    foreach (explode(',', $header) as $item) {
        $pair = explode('=', trim($item), 2);
        if (count($pair) === 2) {
            $parts[$pair[0]] = $pair[1];
        }
    }
    if (empty($parts['t']) || empty($parts['v1'])) {
        return false;
    }
    // 5 dakikadan eski istekleri reddedin
    if (abs(time() - (int) $parts['t']) > 300) {
        return false;
    }
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

Bilmeniz gerekenler

Anahtarı yenilediğinizde eski anahtarla yapılan imzalar geçersiz olur ve durum Doğrulama bekliyor’a döner.
Yeni anahtarla Test gönder başarılı olana kadar talep gönderilmez. Bu sürede açtığınız talepler sonradan da gönderilmez.
Adresi değiştirmek anahtarı değiştirmez.
X-ClinicVi-Event başlığı olay türünü taşır: açılan talepte lead.unlocked, testte webhook.test.
Anahtarı yalnız klinik sahibi ya da yöneticisi yenileyebilir.

Sık sorulanlar

Anahtarımı tekrar görebilir miyim?

Hayır. Anahtar güvenlik için yalnız oluşturulduğu anda bir kez gösterilir. Kaydetmediyseniz Anahtarı yenile ile yenisini oluşturun.

İmzayı doğrulamak zorunlu mu?

ClinicVi istekleri her zaman imzalı gönderir; doğrulama sizin tarafınızda yapılır. Adresinizi öğrenen başka birinin sahte istek göndermesini engellemek için doğrulamanızı öneririz.

Aynı talep iki kez geldi.

Gönderim nadiren tekrar edebilir. X-ClinicVi-Delivery değeri aynı olan ikinci isteği yok sayın.

İlgili makaleler

Hâlâ takıldınız mı? Ekibimize WhatsApp'tan yazın. Ekranın görüntüsünü gönderirseniz daha hızlı çözeriz.