Skip to Content
Apex Settlement

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"]
  }'
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"
}

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:

  • url must be https, reachable on the public internet, and carry no user name or password. Private, loopback and link-local addresses are refused with webhook_url_invalid.
  • events lists 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

TypeSent whendata holds
payout.updatedA Payout you sent changes state.The Payout, as GET /v1/payouts/{id} returns it, with its timeline.
payout.incoming.updatedA 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.receivedA Deposit is credited to your balance.asset, amount and received_at.
beneficiary.updatedA 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

payout.updated (trimmed)
{
  "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.

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"
  }
}

An Incoming Payout's status is on_the_way, delivered, delayed or returned.

Delivery headers

HeaderValue
Content-Typeapplication/json
User-AgentApex-Webhooks/1
Apex-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
Apex-Event-IdThe event's id
Apex-Event-TypeThe event's type
Apex-Delivery-Attempt1 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=5f1c9a7e0b3d42c6a8e1f7b9d3c5a0e2f4b6d8a1c3e5f7091b2d4f6a8c0e2b4d
  • t is when this attempt was sent, in Unix seconds. Every attempt, retries included, is signed afresh.
  • v1 is 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:

  1. Read the raw request body as bytes, before any JSON parsing. A re-serialised body does not match.
  2. Split the header on , and each part on the first =. Take t, and every v1.
  3. Refuse the delivery if t is more than five minutes from your clock. This stops a captured delivery from being replayed later.
  4. Compute HMAC-SHA256 over t, a . and the raw body, with the secret as the key.
  5. Compare it with each v1 in 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 attemptNext attempt in
130 seconds
21 minute
32 minutes
44 minutes
58 minutes
616 minutes
732 minutes
864 minutes
9128 minutes
10 to 144 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
curl "$APEX_BASE_URL/v1/webhooks/e4b8a2c6-1f3d-4b9e-8a70-5c2d9f1e3b47/deliveries?limit=20" \
  -H "Authorization: Bearer $APEX_API_KEY"
200 OK (one delivery, payload trimmed)
[
  {
    "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:

  1. Deploy your receiver so it accepts a signature made with either the current or a new secret (read both from configuration).
  2. Rotate, and add the new secret to the configuration.
  3. 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:

payout.updated for an End Customer (trimmed)
{
  "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 (and Apex-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_at with 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.updated events can both show processing when 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/payouts to find what you missed.

On this page