Webhooks
Receive signed events about your Payouts, Deposits and Beneficiaries, verify them, and handle retries.
How webhooks work
When one of your Payouts, Deposits or Beneficiaries changes, we send a signed POST with the change to every webhook endpoint you subscribed to that event. We retry until your endpoint answers 2xx, for about a day. Each event carries the resource as the API would return it, so you rarely need to call back.
Register an endpoint
Register endpoints in the Customer panel under Webhooks, or with an API key that holds customer:webhooks:manage:
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"
}The signing secret is shown once
secret appears only in this answer and in the answer to a secret rotation. Store it in your secret store. If you lose it, rotate it.
Rules for an endpoint:
urlmust behttps, reachable on the public internet, and carry no user name or password. Private, loopback and link-local addresses are refused withwebhook_url_invalid.eventslists one to three event types. To receive all four, register a second endpoint for the rest; it can point at the same URL, and it gets its own secret.- An account registers at most 10 endpoints, disabled ones included (
webhook_endpoint_limit). - Endpoints cannot be edited. To change the URL or the events, register a new endpoint and disable the old one.
Event types
| Type | Sent when | data holds |
|---|---|---|
payout.updated | A Payout you sent changes state. | The Payout, as GET /v1/payouts/{id} returns it, with its timeline. |
payout.incoming.updated | A Payout another Customer sent you with your Receiving Code changes status as you see it. | The Incoming Payout, as GET /v1/incoming-payouts/{id} returns it. |
deposit.received | A Deposit is credited to your balance. | asset, amount and received_at. |
beneficiary.updated | A Beneficiary of yours is registered or changes state, for example to verified or blocked. | The Beneficiary, as GET /v1/beneficiaries/{id} returns it. |
The payload
Every delivery has the same envelope:
Prop
Type
{
"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" } }
]
}
}The Payout in an event has no initiated_by_you: an event has no caller. Use initiated_by.
{
"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"
}
}An Incoming Payout's status is on_the_way, delivered, delayed or returned.
Delivery headers
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Apex-Webhooks/1 |
Apex-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
Apex-Event-Id | The event's id |
Apex-Event-Type | The event's type |
Apex-Delivery-Attempt | 1 on the first attempt, then 2, 3 and so on |
Verify the signature
Apex-Signature proves that we sent the delivery and that nobody changed it:
Apex-Signature: t=1794477731,v1=5f1c9a7e0b3d42c6a8e1f7b9d3c5a0e2f4b6d8a1c3e5f7091b2d4f6a8c0e2b4dtis when this attempt was sent, in Unix seconds. Every attempt, retries included, is signed afresh.v1is the lowercase hex HMAC-SHA256 of the string<t>.<raw body>, keyed with your endpoint's whole secret,whsec_prefix included.
To verify a delivery:
- Read the raw request body as bytes, before any JSON parsing. A re-serialised body does not match.
- Split the header on
,and each part on the first=. Taket, and everyv1. - Refuse the delivery if
tis more than five minutes from your clock. This stops a captured delivery from being replayed later. - Compute HMAC-SHA256 over
t, a.and the raw body, with the secret as the key. - Compare it with each
v1in constant time. Accept if one matches.
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);
});Respond fast, then retry rules
Answer with any 2xx status within 10 seconds. Verify the signature, put the event on your own queue, answer, and do the work afterwards.
A delivery fails when there is no answer within 10 seconds, the connection fails, or the status is anything but 2xx. Redirects are not followed: a 3xx is a failure, so register the final URL. A failed delivery is retried with growing waits:
| After failed attempt | Next attempt in |
|---|---|
| 1 | 30 seconds |
| 2 | 1 minute |
| 3 | 2 minutes |
| 4 | 4 minutes |
| 5 | 8 minutes |
| 6 | 16 minutes |
| 7 | 32 minutes |
| 8 | 64 minutes |
| 9 | 128 minutes |
| 10 to 14 | 4 hours |
The 15th attempt is the last, about 24 hours and 15 minutes after the first. The delivery is then failed.
An endpoint that has had no successful delivery for 24 hours is disabled, with disabled_reason set to no successful delivery for 24 hours. Watch failing_since on GET /v1/webhooks: it is set from the first failure after the last success.
Delivery log and redelivery
Every endpoint keeps its deliveries, newest first:
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 is pending while retries remain, then delivered or failed. response_body keeps the first 2 KB of your endpoint's answer.
Send a finished delivery again with POST /v1/webhooks/deliveries/{id}/redeliver. It starts a fresh retry schedule, with Apex-Delivery-Attempt counting from 1 again, and keeps the event's id. A delivery still pending is refused with webhook_delivery_pending, and a disabled endpoint with webhook_endpoint_state (both 409).
Rotate the secret
POST /v1/webhooks/{id}/rotate-secret answers {endpoint, secret} with a new secret, once. Every attempt from that moment on is signed with the new secret, retries of older events included; the old one stops working at once. To rotate without dropping events:
- Deploy your receiver so it accepts a signature made with either the current or a new secret (read both from configuration).
- Rotate, and add the new secret to the configuration.
- Once deliveries verify with the new secret, remove the old one.
Deliveries that fail during the switch are retried, so a short gap costs you nothing.
Disable and enable
POST /v1/webhooks/{id}/disable stops deliveries to an endpoint; POST /v1/webhooks/{id}/enable starts them again. While it is disabled:
- deliveries still pending fail with
endpoint disabled; - events that happen are not queued for it at all.
After enabling an endpoint, redeliver the failed deliveries you need from its log, and read the current state of your Payouts and Beneficiaries with the API to catch up on what happened in between.
End Customer events
A Platform's End Customers cannot register endpoints of their own. Their events go to the Platform's endpoints that subscribe to the type, with end_customer_id set to the End Customer the event is about:
{
"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" }
}To read the resource afterwards, call the API with the Apex-End-Customer header set to that id. See the Platforms guide.
Best practices
- Verify, queue, answer. Check the signature, put the event on your own queue and answer
2xx. Do the work after you answered. - Deduplicate by event id. A retry or a redelivery carries the same
id(andApex-Event-Id). Record the ids you have processed and skip repeats. - Do not rely on order. Deliveries run in parallel and are retried, so events can arrive out of order. Compare the resource's
updated_atwith what you hold and ignore older versions. - Fetch the resource for the truth. When it matters, such as before you release goods, read
GET /v1/payouts/{id}instead of acting on the event alone. - Expect more than one event per state. Two
payout.updatedevents can both showprocessingwhen the Payout moves through internal stages. Treat each event as "this changed; here is its latest state". - Keep a polling fallback. If your endpoint is down for long, list recent Payouts with
GET /v1/payoutsto find what you missed.