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"]
}'{
"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ı:
urlbirhttpsadresi olmalı, herkese açık internetten erişilebilmeli ve kullanıcı adı ya da şifre içermemelidir. Özel, loopback ve link-local adreslerwebhook_url_invalidile reddedilir.eventsbir 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ür | Ne zaman gönderilir | data içeriği |
|---|---|---|
payout.updated | Gönderdiğiniz bir ödemenin durumu değiştiğinde. | GET /v1/payouts/{id} yanıtındaki haliyle, timeline ile birlikte ödeme. |
payout.incoming.updated | Baş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.received | Bakiyenize bir para yatırma eklendiğinde. | asset, amount ve received_at. |
beneficiary.updated | Alı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
{
"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.
{
"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" }
}{
"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"
}
}{
"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ık | Değer |
|---|---|
Content-Type | application/json |
User-Agent | Apex-Webhooks/1 |
Apex-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
Apex-Event-Id | Olayın id değeri |
Apex-Event-Type | Olayı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=5f1c9a7e0b3d42c6a8e1f7b9d3c5a0e2f4b6d8a1c3e5f7091b2d4f6a8c0e2b4dt, 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ınwhsec_ö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:
- İstek gövdesini, herhangi bir JSON ayrıştırmasından önce ham bayt olarak okuyun. Yeniden serileştirilmiş bir gövde eşleşmez.
- Başlığı
,ile, her parçayı ilk=ile bölün.tdeğerini ve tümv1değerlerini alın. tsizin saatinizden beş dakikadan fazla uzaksa gönderimi reddedin. Bu, yakalanmış bir gönderimin sonradan yeniden oynatılmasını engeller.t, bir.ve ham gövde üzerinden, gizli değeri anahtar olarak kullanıp HMAC-SHA256 hesaplayın.- Sonucu her
v1ile 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 deneme | Sonraki deneme |
|---|---|
| 1 | 30 saniye sonra |
| 2 | 1 dakika sonra |
| 3 | 2 dakika sonra |
| 4 | 4 dakika sonra |
| 5 | 8 dakika sonra |
| 6 | 16 dakika sonra |
| 7 | 32 dakika sonra |
| 8 | 64 dakika sonra |
| 9 | 128 dakika sonra |
| 10 ile 14 arası | 4 saat sonra |
- 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 "$APEX_BASE_URL/v1/webhooks/e4b8a2c6-1f3d-4b9e-8a70-5c2d9f1e3b47/deliveries?limit=20" \
-H "Authorization: Bearer $APEX_API_KEY"[
{
"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:
- 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).
- Gizli değeri yenileyin ve yenisini yapılandırmaya ekleyin.
- 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 disabledhatası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:
{
"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
2xxile yanıt verin. İşi yanıttan sonra yapın. - Tekrarları olay kimliğiyle ayıklayın. Yeniden deneme ve yeniden gönderim aynı
iddeğerini (veApex-Event-Idbaş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_atdeğ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.updatedolayının ikisi deprocessinggö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/payoutsile listeleyin.