# Webhooks

> Register HTTPS endpoints for real-time event notifications, HMAC-SHA256-signed over the raw body. Full event catalogue, per-event payloads, signature-verification code (Node & Python), at-least-once delivery semantics, and the delivery log.

Register HTTPS endpoints to receive real-time event notifications. MyStocks signs every delivery with
an HMAC-SHA256 signature over the raw request body using your webhook secret. Your endpoint must
respond HTTP 2xx within **8 seconds**; heavy processing should be deferred to a background queue.
Failed deliveries are retried with exponential backoff — check the delivery log via
`GET /webhooks/{id}/deliveries`.

For mobile foreground UX, use [`GET /stream` Server-Sent Events](/partners/docs/sse-events) to receive the same partner events
with near-real-time delivery and resume via `Last-Event-ID` / `?since=`. Webhooks and SSE carry order,
wallet, KYC, dividend, account, and market-status events; they do **not** provide tick-by-tick quotes
or Level-2 order book depth. Poll `/market/quotes` for fresh displayed prices, and use the
`/users/{userId}/devices` endpoints to manage your own APNs/FCM/Expo/Web Push fanout.

### Financial event durability

Canonical funding, order submission/cancellation/replacement, account closure and KYC events are queued in the same database transaction as their state changes. The event worker dispatches them asynchronously with a stable `eventId`. Consumers must deduplicate that identifier because delivery is at least once. A successful financial HTTP response does not mean the recipient has already received its webhook.

The financial dispatch view in `/admin/partners` distinguishes pending intents, attempts and dispatch handoff. `DISPATCHED` means handoff to the stream/webhook engine; use delivery records to establish recipient success. Legacy Sandbox webhook aliases are compatibility notifications; new integrations should register canonical `/webhooks` events.

## Register a webhook

`POST` `/webhooks`

[Try endpoint: createWebhooks](https://partners.mystocks.africa/partners/docs/api-tester?endpoint=createWebhooks)

url (string, required): HTTPS endpoint. Must respond 2xx within 8 s.

events (string\[], required): Array of event type strings to subscribe to.

secret (string, optional): HMAC signing secret (min 16 chars). Generated automatically if omitted.

```sh
curl -X POST "https://mystocks.africa/api/v1/partner/webhooks" \
-H "Authorization: Bearer pk_live_<key>" \
-H "Idempotency-Key: webhook_primary_001" \
-H "Content-Type: application/json" \
-d '{"url":"https://yourapp.com/webhooks/mystocks","events":["order.filled","order.rejected"],"secret":"my-signing-secret-min-16-chars"}'
```

```javascript
const webhook = await fetch("https://mystocks.africa/api/v1/partner/webhooks", {
method: "POST",
headers: {
  Authorization: "Bearer pk_live_<key>",
  "Idempotency-Key": "webhook_primary_001",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  url: "https://yourapp.com/webhooks/mystocks",
  events: ["order.filled", "order.rejected"],
  secret: "my-signing-secret-min-16-chars",
}),
}).then((res) => res.json());
```

```python
webhook = requests.post(
  "https://mystocks.africa/api/v1/partner/webhooks",
  headers={"Authorization": "Bearer pk_live_<key>", "Idempotency-Key": "webhook_primary_001"},
  json={
      "url": "https://yourapp.com/webhooks/mystocks",
      "events": ["order.filled", "order.rejected"],
      "secret": "my-signing-secret-min-16-chars",
  },
).json()
```

```sdk
const webhook = await client.webhooks.register(
{
  url: "https://yourapp.com/webhooks/mystocks",
  events: ["order.filled", "order.rejected"],
  secret: "my-signing-secret-min-16-chars",
},
{ idempotencyKey: "webhook_primary_001" },
);
```

## Event catalogue

| Event                            | Trigger                                                                                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.pending`                  | An order was submitted and is awaiting live fill.                                                                                           |
| `order.filled`                   | An order was filled and executed. Shares/proceeds credited.                                                                                 |
| `order.rejected`                 | An order was declined. Includes `rejectionCode` and `rejectionReason`.                                                                      |
| `order.cancelled`                | An order was cancelled via `DELETE /orders/{orderId}`.                                                                                      |
| `order.replaced`                 | A resting order was modified via `PATCH /users/{userId}/orders/{orderId}` (same orderId).                                                   |
| `trade.settled`                  | Alias for `order.filled` — use `order.filled` in new integrations.                                                                          |
| `trade.rejected`                 | Alias for `order.rejected` — use `order.rejected` in new integrations.                                                                      |
| `deposit.confirmed`              | A sub-account deposit was recorded.                                                                                                         |
| `withdraw.confirmed`             | A sub-account withdrawal was processed.                                                                                                     |
| `wallet.credited`                | Master wallet received a top-up from MyStocks ops.                                                                                          |
| `kyc.updated`                    | A sub-account KYC status changed. Inspect `kycStatus`: `VERIFIED` unlocks trading; `REJECTED` includes reason evidence and remains blocked. |
| `account.frozen`                 | A sub-account was frozen (or unfrozen) by partner or MyStocks compliance.                                                                   |
| `account.closed`                 | A sub-account was soft-closed/offboarded via `DELETE /users/{userId}`.                                                                      |
| `dividend.paid`                  | A dividend was received and credited to a sub-account.                                                                                      |
| `corporateaction.declared`       | Generic corporate-action event for backwards compatibility.                                                                                 |
| `corporateaction.split`          | Stock split, reverse split, or bonus issue affecting holdings.                                                                              |
| `corporateaction.suspension`     | Trading suspension or halt affecting a listed security.                                                                                     |
| `corporateaction.delisting`      | Delisting event for a listed security.                                                                                                      |
| `corporateaction.rights_issue`   | Rights issue or similar subscription entitlement.                                                                                           |
| `corporateaction.symbol_changed` | Ticker/symbol migration, rename, or exchange code change.                                                                                   |
| `quote.expired`                  | A tradeable quote reached its 60-second TTL without being used.                                                                             |
| `price.alert`                    | A price alert you registered crossed its threshold. See [Price alerts](#price-alerts).                                                      |
| `market.status`                  | An exchange changed phase (OPEN/CLOSED/HOLIDAY).                                                                                            |
| `incident.declared`              | A platform incident affecting your integration was opened.                                                                                  |
| `incident.resolved`              | A previously declared incident was closed.                                                                                                  |

## Price alerts

`price.alert` does not fire on its own — you subscribe to the thresholds you care about. Register one
with `POST /price-alerts`; `threshold` is in the instrument's **local trading currency**, the same
basis as a quote's `price`.

```bash
curl -X POST https://mystocks.africa/api/v1/partner/price-alerts \
  -H "Authorization: Bearer pk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "symbol": "SCOM.KE", "exchange": "NSE", "condition": "above", "threshold": 20.00 }'
```

symbol (string, optional): Required. Must exist and trade on the given exchange.

exchange (string, optional): Required. Exchange code, e.g. NSE, NGX, JSE.

condition (string, optional): Required. "above" or "below".

threshold (number, optional): Required. Positive, in the local trading currency.

repeat (boolean, optional): Default false. When false the alert fires once and disarms. When true it re-arms, but only after the price crosses back through the threshold — so a price hovering at the threshold cannot spam your endpoint.

clientAlertId (string, optional): Optional. Your own reference, echoed back on the alert and in the webhook payload.

Alerts are evaluated against the **live** price and only while the exchange is open, so a stale
closing price can never trigger one. Because quotes are polled on a \~15-minute cycle
(see [Data freshness](/partners/docs/market-data-quotes)), an alert fires on the first poll after the
crossing — not at the instant of the tick. Do not use `price.alert` as an execution trigger; use a
resting `LIMIT` or `STOP` order, which is evaluated on the same cycle but actually places the trade.

List with `GET /price-alerts`, inspect one with `GET /price-alerts/{alertId}`, and remove one with
`DELETE /price-alerts/{alertId}`. You may hold up to 200 active alerts.

```jsonc
// price.alert
{ "event": "price.alert", "timestamp": "2026-07-13T11:45:02Z", "data": { "alertId": "alr_abc123", "clientAlertId": null, "symbol": "SCOM.KE", "exchange": "NSE", "condition": "above", "threshold": 20, "price": 20.15, "currency": "KES", "repeat": false, "state": "DISARMED", "triggeredAt": "2026-07-13T11:45:02.000Z" } }
```

## Delivery envelope

Every delivery wraps the event-specific payload in a standard three-field envelope. Sandbox deliveries
add `isSandbox: true` at the top level.

```json
{ "event": "order.filled", "timestamp": "2026-06-06T10:32:00Z", "data": { "...": "event-specific fields" } }
```

## Event payloads

```jsonc
// order.pending
{ "event": "order.pending", "timestamp": "2026-06-06T10:00:00Z", "data": { "orderId": "ord_abc123", "subAccountId": "usr_abc123", "externalId": "user_42", "type": "BUY", "symbol": "SCOM.KE", "quantity": 1000, "totalCost": 12.67, "status": "PENDING" } }

// order.filled (+ alias trade.settled)
{ "event": "order.filled", "timestamp": "2026-06-06T10:32:00Z", "data": { "orderId": "ord_abc123", "subAccountId": "usr_abc123", "type": "BUY", "symbol": "SCOM.KE", "exchange": "NSE", "quantity": 1000, "feeAmount": 0.09, "status": "FILLED", "settledAt": "2026-06-06T10:32:00Z", "settlementUsdPrice": 0.01261, "totalCost": 12.70 } }

// order.rejected (+ alias trade.rejected) — BUY escrow refunded before this fires
{ "event": "order.rejected", "timestamp": "2026-06-06T10:05:00Z", "data": { "orderId": "ord_abc123", "subAccountId": "usr_abc123", "type": "BUY", "symbol": "SCOM.KE", "quantity": 1000, "status": "REJECTED", "rejectionCode": "LIQUIDITY_UNAVAILABLE", "rejectionReason": "Insufficient market liquidity for this order size." } }

// order.cancelled — BUY includes refunded; SELL has no wallet impact
{ "event": "order.cancelled", "timestamp": "2026-06-06T09:15:00Z", "data": { "orderId": "ord_abc123", "subAccountId": "usr_abc123", "type": "BUY", "symbol": "SCOM.KE", "quantity": 1000, "status": "CANCELLED", "refunded": 12.67, "currency": "USD" } }

// deposit.confirmed — local-currency fields appear when provided in the deposit
{ "event": "deposit.confirmed", "timestamp": "2026-06-06T08:30:00Z", "data": { "subAccountId": "usr_abc123", "externalId": "user_42", "amount": 50.0, "currency": "USD", "newBalance": 150.0, "localAmount": 6500, "localCurrency": "KES", "fxRate": 130.0 } }

// withdraw.confirmed
{ "event": "withdraw.confirmed", "timestamp": "2026-06-06T08:45:00Z", "data": { "subAccountId": "usr_abc123", "amount": 25.0, "currency": "USD", "newBalance": 125.0 } }

// wallet.credited — master wallet top-up fulfilled
{ "event": "wallet.credited", "timestamp": "2026-06-06T09:00:00Z", "data": { "amount": 500.0, "newBalance": 1500.0, "currency": "USD" } }

// corporateaction.split (also sent as corporateaction.declared)
{ "event": "corporateaction.split", "timestamp": "2026-06-06T09:00:00Z", "data": { "corporateActionId": "ca_abc123", "type": "SPLIT", "symbol": "SCOM.KE", "exchange": "NSE", "ratio": "2:1", "effectiveDate": "2026-07-01", "affectedSubAccounts": [{ "subAccountId": "usr_abc123", "externalId": "user_42", "units": 1000 }] } }

// kyc.updated — overriddenByAdmin: true appears only on admin overrides
{ "event": "kyc.updated", "timestamp": "2026-06-06T11:00:00Z", "data": { "subAccountId": "usr_abc123", "externalId": "user_42", "kycStatus": "VERIFIED", "kycLevel": "FULL", "reference": "sumsub_ref_abc123" } }

// kyc.updated rejection — gate the trading UI and show partner-approved remediation text
{ "event": "kyc.updated", "timestamp": "2026-06-06T11:05:00Z", "data": { "subAccountId": "usr_abc123", "externalId": "user_42", "kycStatus": "REJECTED", "kycLevel": "NONE", "reasonCode": "DOCUMENT_EXPIRED", "reason": "Submit a current government-issued identity document.", "reviewedAt": "2026-06-06T11:05:00Z" } }

// account.frozen — frozen boolean distinguishes freeze/unfreeze
{ "event": "account.frozen", "timestamp": "2026-06-06T12:00:00Z", "data": { "subAccountId": "usr_abc123", "frozen": true, "frozenBy": "platform_admin" } }

// account.closed
{ "event": "account.closed", "timestamp": "2026-06-06T12:05:00Z", "data": { "subAccountId": "usr_abc123", "externalId": "user_42", "status": "closed", "residualTransferUsd": 0, "currency": "USD" } }

// dividend.paid — one per distribution batch, grouped by symbol
{ "event": "dividend.paid", "timestamp": "2026-06-06T09:00:00Z", "data": { "symbol": "SCOM.KE", "dividendPerShare": 0.00065, "currency": "KES", "totalUsdPaid": 0.65, "distributions": [{ "subAccountId": "usr_abc123", "units": 1000, "usdYield": 0.50 }] } }

// incident.declared — severity P0 (critical) → P3 (minor)
{ "event": "incident.declared", "timestamp": "2026-06-06T14:00:00Z", "data": { "id": "inc_abc123", "title": "NGX market data delay", "severity": "P2", "affectedServices": ["market-data"], "status": "investigating" } }

// incident.resolved — duration is a human-readable string
{ "event": "incident.resolved", "timestamp": "2026-06-06T16:30:00Z", "data": { "id": "inc_abc123", "severity": "P2", "status": "resolved", "resolvedAt": "2026-06-06T16:30:00Z", "duration": "2h 30m" } }
```

## Signature verification

Every delivery includes an `x-mystocks-signature` header containing an HMAC-SHA256 hex digest of the
raw request body signed with your webhook secret. Always verify using a constant-time comparison.

```javascript
const crypto = require('crypto');

app.post('/webhooks/mystocks', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-mystocks-signature'].replace(/^sha256=/i, '');
  const expected = crypto
    .createHmac('sha256', process.env.MYSTOCKS_WEBHOOK_SECRET)
    .update(req.body) // raw Buffer — do NOT parse JSON first
    .digest('hex');

  const verified = crypto.timingSafeEqual(
    Buffer.from(sig, 'utf8'),
    Buffer.from(expected, 'utf8'),
  );
  if (!verified) return res.status(401).send('Invalid signature');

  const event = JSON.parse(req.body);
  res.status(200).send('OK');
});
```

```python
import hmac, hashlib, os, json
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()

@app.post("/webhooks/mystocks")
async def handle_webhook(request: Request, x_mystocks_signature: str = Header(...)):
    payload = await request.body()
    expected = hmac.new(
        key=os.getenv("MYSTOCKS_WEBHOOK_SECRET").encode(),
        msg=payload,
        digestmod=hashlib.sha256,
    ).hexdigest()
    supplied = x_mystocks_signature.removeprefix("sha256=")
    if not hmac.compare_digest(supplied, expected):
        raise HTTPException(status_code=401, detail="Invalid signature")
    event = json.loads(payload)
    return {"status": "ok"}
```

> **Delivery semantics — at-least-once, not exactly-once.** The same event can arrive more than once;
> events are not guaranteed to arrive in order (a retried `order.pending` can land after
> `order.filled`); and a delivery can fail all retries. The robust pattern: **dedupe by `eventId`**,
> treat handlers as idempotent, and derive state from the event *payload* rather than arrival order.
> Respond `2xx` quickly and process asynchronously — you have 8 seconds before the attempt fails.

## Manage & inspect

`GET` `/webhooks` · `DELETE` `/webhooks/{id}` · `POST` `/webhooks/{id}/test` · `GET` `/webhooks/{id}/deliveries`

[Try endpoint: listDeliveries](https://partners.mystocks.africa/partners/docs/api-tester?endpoint=listDeliveries)

List registered webhooks, delete one, fire a test event, or inspect delivery history.
`POST /webhooks/{id}/test` sends a `test.event` payload immediately and logs the delivery — useful for
verifying reachability and signature verification before going live. `/deliveries` returns each attempt
with HTTP status, response snippet, duration (ms), and the retry schedule if it failed. Retry schedule:
immediate → 5 s → 30 s → 5 min → 30 min → 2 h (6 attempts max).

```bash
# Fire a test.event delivery immediately
curl -X POST "https://mystocks.africa/api/v1/partner/webhooks/wh_abc123/test" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Idempotency-Key: webhook-test-wh_abc123-2026-08-10"

# Inspect delivery log
curl "https://mystocks.africa/api/v1/partner/webhooks/wh_abc123/deliveries?limit=10" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "deliveries": [{ "id": "del_abc", "eventId": "evt_abc123", "event": "order.filled", "status": 200, "duration": 142, "attemptedAt": "2026-06-04T11:30:01Z", "success": true }, { "id": "del_def", "eventId": "evt_def456", "event": "deposit.confirmed", "status": 503, "duration": 8000, "success": false, "nextRetryAt": "2026-06-04T10:05:00Z" }], "count": 2, "hasMore": false, "nextCursor": null }
```

## Durable financial event recovery

Financial mutations commit notification intents with their state changes. The worker scans a bounded cursor-based queue, applies a per-partner dispatch budget and retains a stable event ID. Failed handoffs back off and enter `DEAD_LETTER` after eight attempts. Administrators must investigate worker/receiver health before an audited redrive. Redrive retries notification handoff only; it never repeats the financial mutation.

`DISPATCHED` means handoff to the event/webhook engine, not recipient delivery. Consumers deduplicate event IDs. Review signed receiver delivery, retries and stream replay independently. A limited admin queue sample is not a complete backlog count.
