İçeriğe geç

Webhook

Olayları kendi adresinize almak: imza doğrulama, yeniden deneme, tekilleştirme.

Geliştirici belgesi

Webhook, hesabınızdaki bir olay olduğunda (çalışan eklendi, izin onaylandı) sizin HTTPS adresinize imzalı bir POST isteği gönderir. Olay türleri ve gövde alanları Olay kataloğu'ndadır.

Uç oluşturma

Hesap sahibi Ayarlar › API › Webhook ekranında Yeni uç'a basar; adresi, açıklamayı ve almak istediği olay türlerini seçip Uç oluştur der. Oluşturma ek doğrulama ister.

  • Adres https:// ile başlar ve 443 portunu kullanır. IP adresi, kullanıcı bilgisi ve iç ağ adları kabul edilmez; adın çözüldüğü adreslerin hepsi genel internette olmalıdır. Bu denetim her teslimde yeniden yapılır.
  • Uç, oluşturan kişinin görebildiği modüllerin olaylarını ve onun bağlamasını (tüm hesap ya da tek şirket) alır. Oluşturanın yetkisi daralırsa uç ilgili olayları almayı bırakır.
  • İmza sırrı whsec_ ile başlar ve yalnız bir kez gösterilir.
  • Uç düzenlenmez: adresi ya da olayları değiştirmek için ucu silip yeniden oluşturun.

İstek

POST /sizin/yolunuz HTTP/1.1
Content-Type: application/json
webhook-id: 2d8f6a4e-91b3-4c7d-8e5f-0a1b2c3d4e5f
webhook-timestamp: 1781597100
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

Gövde:

{
  "id": "6f5e4d3c-2b1a-4c9d-8e7f-6a5b4c3d2e1f",
  "type": "employee.created",
  "timestamp": "2026-06-16T08:05:00.412Z",
  "sequence": 4182,
  "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
  "subject": {
    "type": "employee",
    "id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  },
  "data": {
    "employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
    "status": "active",
    "hire_date": "2026-06-16"
  }
}
  • id: olayın kimliği. type: olay türü. timestamp: olayın olduğu an (UTC).
  • sequence: hesap içinde artan sıra numarası. Sıra garantisi vermez (aşağıda).
  • company_id: olayın şirketi. subject: olayın konusu olan kaydın türü ve kimliği.
  • data: türün ince gövdesi. Gövde kimlik, durum ve gün taşır; ad, serbest metin, tutar, T.C. kimlik numarası, IBAN ve sağlık bilgisi taşımaz. Ayrıntıyı API'den kendi kapsamınızla okuyun.

İmzayı doğrulama

İmza Standard Webhooks belirtimindedir: webhook-signature değeri v1, ve webhook-id.webhook-timestamp.gövde metninin HMAC-SHA256 imzasının base64 hâlidir. Anahtar, sırrın whsec_ önekinden sonraki base64'ün çözülmüş baytlarıdır.

Doğrularken:

  • Ham gövdeyi kullanın: JSON'u ayrıştırıp yeniden yazmak baytları değiştirir ve imza tutmaz.
  • webhook-timestamp şimdiki zamandan 5 dakikadan daha eski ya da daha ileriyse isteği reddedin (yeniden oynatma koruması).
  • Karşılaştırmayı sabit zamanlı yapın.
  • Başlık boşlukla ayrılmış birden çok imza taşıyabilir (sır döndürülürken); biri tutarsa istek geçerlidir.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 5 * 60;

/** headers: küçük harfli başlık adları; rawBody: ham gövde (Buffer ya da string). */
export function verifyWebhook(secret, headers, rawBody, now = Date.now()) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures || !/^\d{1,12}$/.test(timestamp)) return false;
  if (Math.abs(Math.floor(now / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(rawBody).digest();
  return signatures.split(' ').some((entry) => {
    const [version, value] = entry.split(',');
    if (version !== 'v1' || !value) return false;
    const given = Buffer.from(value, 'base64');
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

Bir HTTP sunucusunda kullanımı:

import { createServer } from 'node:http';

import { verifyWebhook } from './verify-webhook.mjs';

const secret = process.env.BIIK_WEBHOOK_SECRET;

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const rawBody = Buffer.concat(chunks);
    if (!verifyWebhook(secret, req.headers, rawBody)) {
      res.writeHead(400).end();
      return;
    }
    // webhook-id daha önce işlendiyse yalnız 2xx dönün.
    const event = JSON.parse(rawBody.toString('utf8'));
    console.log(req.headers['webhook-id'], event.type);
    res.writeHead(204).end();
  });
}).listen(8080);

Python

import base64
import binascii
import hashlib
import hmac
import re
import time

TOLERANCE_SECONDS = 5 * 60


def verify_webhook(secret, headers, raw_body, now=None):
    """headers: küçük harfli başlık adları; raw_body: ham gövde (bytes)."""
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures:
        return False
    if not re.fullmatch(r"[0-9]{1,12}", timestamp):
        return False
    current = time.time() if now is None else now
    if abs(int(current) - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = msg_id.encode() + b"." + timestamp.encode() + b"." + raw_body
    expected = hmac.new(key, signed, hashlib.sha256).digest()
    for entry in signatures.split(" "):
        version, _, value = entry.partition(",")
        if version != "v1":
            continue
        try:
            given = base64.b64decode(value, validate=True)
        except (binascii.Error, ValueError):
            continue
        if hmac.compare_digest(given, expected):
            return True
    return False

Bu iki örnek her derlemede bir başvuru imzasıyla ve gerçek teslimlerle sınanır: değişmiş bir bayt ve 5 dakikadan eski damga reddedilir.

Yanıt ve yeniden deneme

  • İsteği aldığınızı 15 saniye içinde 2xx ile bildirin. Uzun işi kuyruğa alıp hemen yanıt verin. Art arda 3 kez zaman aşımına düşen uca, ilk başarılı teslime kadar 5 saniye tanınır.
  • 2xx dışındaki her yanıt ve zaman aşımı başarısız sayılır. Yönlendirme (3xx) izlenmez ve başarısızdır.
  • Bir olay en çok 10 kez denenir. Denemeler arasındaki bekleme: hemen, 5 sn, 5 dk, 30 dk, 2 sa, 5 sa, 10 sa, 14 sa, 20 sa, 24 sa. Aralıklar rastgele biraz uzatılır. 429 ya da 503 yanıtındaki Retry-After çizelgeden uzunsa ona uyulur.
  • 410 Gone yanıtı ucu kapatır. 5 gün boyunca kesintisiz başarısız olan uç da kapanır; iki durumda da hesap sahiplerine bildirim gider.
  • Teslim günlüğü ekranda 30 gün tutulur. Sonuçlanmış bir teslimi ekrandan elle yeniden gönderebilirsiniz; aynı webhook-id ile gider.

Tekilleştirme ve sıra

  • Aynı teslim birden fazla kez gelebilir (örneğin yanıtınız yolda kaybolursa). webhook-id yeniden denemelerde ve elle yeniden gönderimde aynıdır: işlediğiniz kimlikleri saklayın ve yineleneni yalnız 2xx ile yanıtlayın.
  • Sıra garanti edilmez. Yeniden denemeler yüzünden sonra olan bir olay önce gelebilir. Sıraya ihtiyacınız varsa timestamp'e bakın ya da kaydın güncel hâlini API'den okuyun.
  • Gövde bir kez üretilir: aynı teslimin her denemesi aynı baytları gönderir, yalnız webhook-timestamp ve imza yenilenir.

Sır döndürme

Ekrandan Sırrı döndür yeni bir sır verir. Geçiş süresince (varsayılan 24 saat, en çok 7 gün) her teslim iki imza taşır: önce yeni sırla, sonra eskisiyle. Doğrulama kodunuz iki sırrı da denerse kesinti olmaz.

Deneme olayı

Uç kartındaki Deneme olayı gönder yalnız o uca bir webhook.ping olayı gönderir. Adresinizin ve imza doğrulamanızın çalıştığını böyle sınayın.

Sınırlar

Hesap başına en çok 10 uç, uç başına en çok 10 özel başlık. Gövde en çok 256 KiB'tir. Alıcının yanıtından yalnız ilk 512 bayt teslim günlüğünde saklanır.