İçeriğe geç
Apex Settlement

Webhook'lar

Ödemeleriniz, para yatırmalarınız ve alıcılarınızla ilgili imzalı olayları alın, doğrulayın ve yeniden denemeleri yönetin.

Webhook'lar nasıl çalışır

Ödemelerinizden, para yatırmalarınızdan ya da alıcılarınızdan biri değiştiğinde, o olaya abone olan her webhook uç noktanıza değişikliği içeren imzalı bir POST göndeririz. Uç noktanız 2xx ile yanıt verene kadar, yaklaşık bir gün boyunca yeniden deneriz. Her olay, kaynağı API'nin döneceği haliyle taşır; bu yüzden çoğu zaman geri çağırmanıza gerek kalmaz.

Bir uç nokta kaydedin

Uç noktaları müşteri panelinde Webhook'lar sayfasından ya da customer:webhooks:manage iznine sahip bir API anahtarıyla kaydedin:

curl -X POST "$APEX_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $APEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/apex",
    "events": ["payout.updated", "deposit.received", "beneficiary.updated"]
  }'
201 Created
{
  "endpoint": {
    "id": "e4b8a2c6-1f3d-4b9e-8a70-5c2d9f1e3b47",
    "url": "https://hooks.example.com/apex",
    "events": ["payout.updated", "deposit.received", "beneficiary.updated"],
    "status": "active",
    "last_success_at": null,
    "failing_since": null,
    "created_at": "2026-11-12T09:30:00Z",
    "updated_at": "2026-11-12T09:30:00Z"
  },
  "secret": "whsec_3b8f1c0e5a9d47e2b6c4f81a0d9e3c7b5a2f6e1d8c4b0a9f7e3d2c1b5a4f6e8d"
}

İmza gizli değeri yalnızca bir kez gösterilir

secret yalnızca bu yanıtta ve gizli değer yenileme yanıtında görünür. Gizli değer deponuzda saklayın. Kaybederseniz yenileyin.

Bir uç noktanın kuralları:

  • url bir https adresi olmalı, herkese açık internetten erişilebilmeli ve kullanıcı adı ya da şifre içermemelidir. Özel, loopback ve link-local adresler webhook_url_invalid ile reddedilir.
  • events bir ile üç arasında olay türü listeler. Dördünü birden almak için kalanlar için ikinci bir uç nokta kaydedin; aynı URL'yi gösterebilir ve kendi gizli değerini alır.
  • Bir hesap, devre dışı olanlar dahil en fazla 10 uç nokta kaydedebilir (webhook_endpoint_limit).
  • Uç noktalar düzenlenemez. URL'yi ya da olayları değiştirmek için yeni bir uç nokta kaydedin ve eskisini devre dışı bırakın.

Olay türleri

TürNe zaman gönderilirdata içeriği
payout.updatedGönderdiğiniz bir ödemenin durumu değiştiğinde.GET /v1/payouts/{id} yanıtındaki haliyle, timeline ile birlikte ödeme.
payout.incoming.updatedBaşka bir müşterinin Alım Kodunuzla size gönderdiği bir ödemenin, sizin gördüğünüz durumu değiştiğinde.GET /v1/incoming-payouts/{id} yanıtındaki haliyle gelen ödeme.
deposit.receivedBakiyenize bir para yatırma eklendiğinde.asset, amount ve received_at.
beneficiary.updatedAlıcılarınızdan biri kaydedildiğinde ya da durumu değiştiğinde, örneğin verified ya da blocked olduğunda.GET /v1/beneficiaries/{id} yanıtındaki haliyle alıcı.

Gövde

Her gönderim aynı zarfı taşır:

Alan

Tür

payout.updated (kısaltılmış)
{
  "id": "2f9d7c1a-6e4b-5a83-9d02-b7c5e1f3a846",
  "type": "payout.updated",
  "created_at": "2026-11-12T10:02:11Z",
  "data": {
    "id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13",
    "state": "completed",
    "send": { "amount": "1000", "asset": "USDC" },
    "receive": { "amount": "918.58", "asset": "EUR" },
    "beneficiary": { "id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84", "name": "Muster GmbH", "country": "DE", "party_type": "business" },
    "delivered_to": "bank_account",
    "legs": [
      { "index": 0, "provider": "bvnk", "from": "USDC", "to": "EUR", "state": "completed", "settled_at": "2026-11-12T10:01:04Z" },
      { "index": 1, "provider": "bvnk", "from": "EUR", "to": "EUR", "state": "completed", "settled_at": "2026-11-12T10:02:11Z" }
    ],
    "cancellable": false,
    "created_at": "2026-11-12T10:00:20Z",
    "updated_at": "2026-11-12T10:02:11Z",
    "timeline": [
      { "state": "accepted", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
      { "state": "completed", "at": "2026-11-12T10:02:11Z", "by": { "actor": "system" } }
    ]
  }
}

Bir olaydaki ödemede initiated_by_you alanı bulunmaz, çünkü olayın bir çağıranı yoktur. Bunun yerine initiated_by alanını kullanın.

deposit.received
{
  "id": "5c0e8b3d-2a7f-5e14-8c96-d4b1a3f7e092",
  "type": "deposit.received",
  "created_at": "2026-11-12T09:12:45Z",
  "data": { "asset": "USDC", "amount": "1000", "received_at": "2026-11-12T09:12:45Z" }
}
beneficiary.updated
{
  "id": "9a4f2e6c-8d1b-5c37-a0e5-3b7d9f2c4a18",
  "type": "beneficiary.updated",
  "created_at": "2026-11-12T09:55:02Z",
  "data": {
    "id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
    "kind": "external",
    "state": "verified",
    "party_type": "business",
    "name": "Muster GmbH",
    "country": "DE",
    "asset": "EUR",
    "details": { "iban": "••••3000", "name": "Muster GmbH" },
    "available": true,
    "verified_at": "2026-11-12T09:55:02Z",
    "created_at": "2026-11-12T09:41:07Z",
    "updated_at": "2026-11-12T09:55:02Z"
  }
}
payout.incoming.updated
{
  "id": "6d2b9f4e-1c8a-5f73-b2d6-e9a1c5f3b740",
  "type": "payout.incoming.updated",
  "created_at": "2026-11-12T11:20:31Z",
  "data": {
    "id": "f2c8a6e4-3b1d-4f9a-8e7c-5d2b1a9f3e60",
    "sender_name": "Tom Trading Inc",
    "amount": { "amount": "30690", "asset": "PKR" },
    "purpose": "services",
    "status": "delivered",
    "delivered_to": "balance",
    "account_hint": "",
    "created_at": "2026-11-12T11:18:02Z",
    "delivered_at": "2026-11-12T11:20:31Z",
    "updated_at": "2026-11-12T11:20:31Z"
  }
}

Bir gelen ödemenin status alanı on_the_way (Yolda), delivered (Teslim edildi), delayed (Gecikti) ya da returned (İade edildi) olur.

Gönderim başlıkları

BaşlıkDeğer
Content-Typeapplication/json
User-AgentApex-Webhooks/1
Apex-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
Apex-Event-IdOlayın id değeri
Apex-Event-TypeOlayın type değeri
Apex-Delivery-Attemptİlk denemede 1, sonra 2, 3 ve devamı

İmzayı doğrulayın

Apex-Signature, gönderimi bizim yaptığımızı ve kimsenin onu değiştirmediğini kanıtlar:

Apex-Signature: t=1794477731,v1=5f1c9a7e0b3d42c6a8e1f7b9d3c5a0e2f4b6d8a1c3e5f7091b2d4f6a8c0e2b4d
  • t, bu denemenin gönderildiği an, Unix saniyesi olarak. Yeniden denemeler dahil her deneme yeniden imzalanır.
  • v1, <t>.<ham gövde> metninin, uç noktanızın whsec_ ön eki dahil gizli değerinin tamamı anahtar olarak kullanılarak alınmış HMAC-SHA256 değeridir; küçük harfli hex.

Bir gönderimi doğrulamak için:

  1. İstek gövdesini, herhangi bir JSON ayrıştırmasından önce ham bayt olarak okuyun. Yeniden serileştirilmiş bir gövde eşleşmez.
  2. Başlığı , ile, her parçayı ilk = ile bölün. t değerini ve tüm v1 değerlerini alın.
  3. t sizin saatinizden beş dakikadan fazla uzaksa gönderimi reddedin. Bu, yakalanmış bir gönderimin sonradan yeniden oynatılmasını engeller.
  4. t, bir . ve ham gövde üzerinden, gizli değeri anahtar olarak kullanıp HMAC-SHA256 hesaplayın.
  5. Sonucu her v1 ile sabit zamanlı karşılaştırın. Biri eşleşirse kabul edin.
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.APEX_WEBHOOK_SECRET; // the whole whsec_... string
const TOLERANCE_SECONDS = 300;

export function verifyApexSignature(rawBody, header, secret, nowMs = Date.now()) {
  if (!header) return false;
  let timestamp;
  const signatures = [];
  for (const part of header.split(",")) {
    const i = part.indexOf("=");
    if (i < 0) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === "t") timestamp = value;
    if (key === "v1") signatures.push(value);
  }
  if (!timestamp || !/^\d+$/.test(timestamp) || signatures.length === 0) return false;
  if (Math.abs(Math.floor(nowMs / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest();
  return signatures.some((sig) => {
    if (!/^[0-9a-f]{64}$/i.test(sig)) return false;
    return crypto.timingSafeEqual(Buffer.from(sig, "hex"), expected);
  });
}

const app = express();

// express.raw keeps the body as the exact bytes we signed.
app.post("/apex", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyApexSignature(req.body, req.get("Apex-Signature"), SECRET)) {
    return res.status(400).send("invalid signature");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  enqueue(event); // your own queue; deduplicate on event.id there
  res.sendStatus(204);
});

Hızlı yanıt verin; yeniden deneme kuralları

10 saniye içinde herhangi bir 2xx durumuyla yanıt verin. İmzayı doğrulayın, olayı kendi kuyruğunuza koyun, yanıt verin ve işi sonra yapın.

Bir gönderim şu durumlarda başarısız sayılır: 10 saniye içinde yanıt gelmezse, bağlantı kurulamazsa ya da durum kodu 2xx dışında bir şeyse. Yönlendirmeler izlenmez: bir 3xx başarısızlıktır, bu yüzden son URL'yi kaydedin. Başarısız bir gönderim artan aralıklarla yeniden denenir:

Başarısız denemeSonraki deneme
130 saniye sonra
21 dakika sonra
32 dakika sonra
44 dakika sonra
58 dakika sonra
616 dakika sonra
732 dakika sonra
864 dakika sonra
9128 dakika sonra
10 ile 14 arası4 saat sonra
  1. deneme sonuncudur; ilkinden yaklaşık 24 saat 15 dakika sonra yapılır. Ardından gönderim failed (Başarısız) olur.

24 saattir hiç başarılı gönderim almayan bir uç nokta devre dışı bırakılır ve disabled_reason alanı no successful delivery for 24 hours olur. GET /v1/webhooks yanıtındaki failing_since alanını izleyin: son başarıdan sonraki ilk başarısızlıktan itibaren dolar.

Gönderim kaydı ve yeniden gönderim

Her uç nokta gönderimlerini en yeniden eskiye sıralı tutar:

curl
curl "$APEX_BASE_URL/v1/webhooks/e4b8a2c6-1f3d-4b9e-8a70-5c2d9f1e3b47/deliveries?limit=20" \
  -H "Authorization: Bearer $APEX_API_KEY"
200 OK (tek gönderim, gövde kısaltılmış)
[
  {
    "id": "b6a1d3e9-2c7f-4e58-a9b4-0d8e6f2c1a75",
    "event_id": "2f9d7c1a-6e4b-5a83-9d02-b7c5e1f3a846",
    "event_type": "payout.updated",
    "state": "pending",
    "attempt": 3,
    "next_attempt_at": "2026-11-12T10:06:41Z",
    "response_status": 503,
    "response_body": "upstream unavailable",
    "duration_ms": 412,
    "last_error": "endpoint answered 503",
    "payload": { "id": "2f9d7c1a-6e4b-5a83-9d02-b7c5e1f3a846", "type": "payout.updated" },
    "created_at": "2026-11-12T10:02:11Z",
    "delivered_at": null
  }
]

state, yeniden deneme hakkı kaldıkça pending (Yeniden deneniyor), sonra delivered (Gönderildi) ya da failed (Başarısız) olur. response_body, uç noktanızın yanıtının ilk 2 KB'ını tutar.

Tamamlanmış bir gönderimi POST /v1/webhooks/deliveries/{id}/redeliver ile yeniden gönderin. Yeni bir deneme takvimi başlar (Apex-Delivery-Attempt yeniden 1'den sayar) ve olayın id değeri korunur. Hâlâ pending olan bir gönderim webhook_delivery_pending ile, devre dışı bir uç noktaya yeniden gönderim de webhook_endpoint_state ile reddedilir (ikisi de 409).

Gizli değeri yenileyin

POST /v1/webhooks/{id}/rotate-secret, yeni gizli değeri bir kez gösteren {endpoint, secret} yanıtını döner. O andan itibaren eski olayların yeniden denemeleri dahil her deneme yeni gizli değerle imzalanır; eskisi hemen geçersiz olur. Olay kaçırmadan yenilemek için:

  1. Alıcı uygulamanızı, hem mevcut hem de yeni gizli değerle yapılmış imzayı kabul edecek şekilde güncelleyin (ikisini de yapılandırmadan okuyun).
  2. Gizli değeri yenileyin ve yenisini yapılandırmaya ekleyin.
  3. Gönderimler yeni gizli değerle doğrulanmaya başlayınca eskisini kaldırın.

Geçiş sırasında başarısız olan gönderimler yeniden denenir; kısa bir boşluk size bir şey kaybettirmez.

Devre dışı bırakın ve etkinleştirin

POST /v1/webhooks/{id}/disable bir uç noktaya gönderimi durdurur; POST /v1/webhooks/{id}/enable yeniden başlatır. Uç nokta devre dışıyken:

  • hâlâ bekleyen gönderimler endpoint disabled hatasıyla başarısız olur;
  • bu sürede olan olaylar onun için hiç kuyruğa alınmaz.

Uç noktayı etkinleştirdikten sonra ihtiyacınız olan başarısız gönderimleri kayıttan yeniden gönderin ve aradaki değişiklikleri yakalamak için ödemelerinizin ve alıcılarınızın güncel durumunu API'den okuyun.

End Customer olayları

Bir Platformun End Customer'ları kendi uç noktalarını kaydedemez. Onların olayları, Platformun o türe abone olan uç noktalarına gider ve olayın ilgili olduğu End Customer end_customer_id alanında belirtilir:

Bir End Customer için payout.updated (kısaltılmış)
{
  "id": "0e7a3c5f-9b2d-5d41-8f6a-c1e3b5d7f924",
  "type": "payout.updated",
  "created_at": "2026-11-12T12:04:40Z",
  "end_customer_id": "8a3f5d27-c1e9-4b64-9d0a-6e2b7f4c1d93",
  "data": { "id": "1b9e5d3f-7c2a-4e86-9a1d-4f6b8c0e2d57", "state": "processing" }
}

Kaynağı sonradan okumak için API'yi, Apex-End-Customer başlığı bu kimliğe ayarlanmış olarak çağırın. Bkz. Platformlar rehberi.

İyi uygulamalar

  • Doğrula, kuyruğa al, yanıtla. İmzayı kontrol edin, olayı kendi kuyruğunuza koyun ve 2xx ile yanıt verin. İşi yanıttan sonra yapın.
  • Tekrarları olay kimliğiyle ayıklayın. Yeniden deneme ve yeniden gönderim aynı id değerini (ve Apex-Event-Id başlığını) taşır. İşlediğiniz kimlikleri kaydedin, tekrarları atlayın.
  • Sıraya güvenmeyin. Gönderimler paralel yürür ve yeniden denenir; olaylar sırası karışık gelebilir. Kaynağın updated_at değerini elinizdekiyle karşılaştırın ve eski sürümleri yok sayın.
  • Doğruyu kaynaktan okuyun. Önemli olduğunda, örneğin malı teslim etmeden önce, yalnızca olaya göre davranmak yerine GET /v1/payouts/{id} ile okuyun.
  • Aynı durum için birden çok olay bekleyin. Ödeme iç aşamalardan geçerken iki payout.updated olayının ikisi de processing gösterebilir. Her olayı "bu değişti; işte son hali" olarak ele alın.
  • Yedek olarak yoklamayı koruyun. Uç noktanız uzun süre kapalı kalırsa kaçırdıklarınızı bulmak için son ödemeleri GET /v1/payouts ile listeleyin.

Bu sayfada