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
2xxile 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. 2xxdışı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.
429ya da503yanıtındakiRetry-Afterçizelgeden uzunsa ona uyulur. 410 Goneyanı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-idile gider.
Tekilleştirme ve sıra
- Aynı teslim birden fazla kez gelebilir (örneğin yanıtınız yolda kaybolursa).
webhook-idyeniden denemelerde ve elle yeniden gönderimde aynıdır: işlediğiniz kimlikleri saklayın ve yineleneni yalnız2xxile 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-timestampve 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.