Webhooks Overview

Pientegra, deposit ve withdrawal state değişikliklerini partner site backend'ine webhook olarak gönderir. Webhook delivery at-least-once çalışır: aynı business event birden fazla kez gelebilir, bu yüzden handler idempotent olmalıdır.

Webhook, status polling'in yerine geçen primary integration channel'dır.

Webhook endpoint setup

İlk entegrasyonda Pientegra ekibine HTTPS endpoint'inizi iletin; size bir API key ve ilk webhook_secret sağlanır. Bu noktadan sonra rotasyon self-serve'dir: PUT /external/site/webhook-config endpoint'i ile URL ve/veya secret'ı kendiniz değiştirebilirsiniz; detay için Webhook Config.

Request body içinde webhookUrl field'ı kabul edilmez: tek delivery target, site kaydında saklanan URL'dir.

Delivery flow

Partner backend                    Pientegra                    Partner webhook
      |                                |                                |
      | POST /withdrawals              |                                |
      |------------------------------->|                                |
      | 200 withdrawalId               |                                |
      |<-------------------------------|                                |
      |                                | (Pientegra processes the       |
      |                                |  withdrawal)                   |
      |                                |                                |
      |                                | POST /your/webhook + HMAC      |
      |                                |------------------------------->|
      |                                |   2xx = delivered, non-2xx     |
      |                                |   = retry per backoff          |
      |                                |<-------------------------------|

Request headers

Payload envelope

Webhook body tek bir JSON object'tir:

{
  "eventId": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
  "eventType": "withdrawal.sent",
  "occurredAt": "2026-04-28T13:15:00.000Z",
  "withdrawal": {
    "id": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
    "referenceNo": "W-2026-0000123",
    "externalUserId": "user-12345",
    "amount": "250000",
    "currency": "TRY",
    "status": "SENT"
  }
}

Financial mutation'lar için sadece eventId saklamakla yetinmeyin. Balance update gibi side effect'leri (eventType, resource.id, resource.status) veya kendi ledger transaction ID'nizle idempotent hale getirin.

Response contract

Handler başarılı işlediği veya daha önce işlenmiş duplicate event gördüğü durumda 2xx dönmelidir. Pientegra 2xx dışındaki response'ları delivery failure kabul eder.

Handler 10 saniye içinde cevap vermelidir. Ağır işleri queue'ya alıp hızlı 200 dönmek en güvenli modeldir.

Retry behavior

Webhook delivery asynchronous retry mekanizmasıyla çalışır. Partner tarafında bilmeniz gereken contract:

Delay sırası yaklaşık 5s, 10s, 20s, 40s, 80s, 160s, 320s şeklindedir. Geçici platform restart'larında retry state korunur; aynı event yeniden gönderilebileceği için handler idempotent kalmalıdır.

Handler checklist

1. Raw body'yi parse etmeden önce signature verify edin.
2. Timestamp tolerance uygulayın.
3. Delivery ID ve business transition için idempotency kaydı tutun.
4. Balance mutation'ı transactional yapın.
5. Duplicate event'te side effect çalıştırmadan 2xx dönün.
6. Ağır işleri background job'a alın; webhook endpoint'i hızlı cevap versin.