DamgaOndiso

Bildirimler (webhook)

Damga, bir imza isteği sonuçlandığında platformunuzun bildirim adresine POST atar. Kullanıcı tarayıcıyı kapatsa, dönüş adresine hiç gelmese de sonucu öğrenirsiniz.

Bildirim adresi platform için tanımlanır; tek bir istek için webhook_url alanıyla değiştirilebilir. Adres https:// olmalıdır.

Olaylar

Olay Ne zaman
sign_request.completed İmza atıldı ve Damga tarafından doğrulandı
sign_request.cancelled Kullanıcı vazgeçti ya da platform iptal etti
sign_request.expired Süre doldu

Gövde

{
  "id": "evt_1842",
  "type": "sign_request.completed",
  "created_at": "2026-10-01T09:02:31Z",
  "data": { "id": "sr_7kq2…", "object": "sign_request", "status": "completed", "reference": "oneri-3", "signature": { "signed_at": "…", "signer": { … } }, … }
}

data, imza isteği nesnesidir; boyutu küçük tutmak için imzanın kendisi (signature.content) ve sertifika PEM'i bildirimde yoktur. İmzayı GET /sign-requests/{id} ya da …/signature ile alın.

Başlıklar ve imza

Başlık Örnek
Damga-Event sign_request.completed
Damga-Delivery evt_1842 (aynı bildirim tekrar gelirse aynı kalır)
Damga-Signature t=1790845351,v1=5f0c…

v1, bildirim anahtarınızla (whsec_…) hesaplanan HMAC-SHA256'dır:

v1 = hex( HMAC_SHA256( whsec_…, t + "." + ham_gövde ) )

Doğrulama adımları:

  1. Damga-Signature'dan t ve v1'i ayırın.
  2. Gövdeyi ayrıştırmadan önce, gelen bayt dizisiyle HMAC'i hesaplayın.
  3. Sabit zamanlı karşılaştırın (hash_equals, crypto.timingSafeEqual, hmac.compare_digest).
  4. t 5 dakikadan eskiyse reddedin (yeniden oynatma).
$body = file_get_contents('php://input');
[$t, $v1] = (function (string $h) {
    parse_str(str_replace(',', '&', $h), $p);
    return [$p['t'] ?? '', $p['v1'] ?? ''];
})($_SERVER['HTTP_DAMGA_SIGNATURE'] ?? '');
$expected = hash_hmac('sha256', $t . '.' . $body, getenv('DAMGA_WEBHOOK_SECRET'));
if (!hash_equals($expected, $v1) || abs(time() - (int) $t) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);

Yanıt ve tekrar

2xx döndüğünüzde bildirim teslim edilmiş sayılır. Başka her durumda (zaman aşımı 5 sn) Damga yeniden dener: 1 dk, 5 dk, 30 dk, 2 sa, 6 sa, 12 sa sonra. Aynı olay birden fazla gelebilir; Damga-Delivery ya da data.id ile tekrarı ayıklayın.

Uzun işleri (PDF'i arşive koymak, e-posta göndermek) bildirim isteği içinde yapmayın: kaydı alıp hemen 200 dönün, işi kuyruğa bırakın.

İpucu: Bildirim ile kullanıcının dönüşü neredeyse aynı anda gelebilir. İmzayı kaydetme işiniz iki kez çağrılsa da aynı sonucu verecek şekilde yazılmalı (ör. sign_request_id üzerinde tekil anahtar).