API product catalogDeveloper Platform, Sandbox & Key Management

Register webhook

Developer Platform, Sandbox & Key Management

POST

/webhooks

Sandbox availablecreateWebhooks

Registers a new HTTPS webhook endpoint. MyStocks sends a POST to your URL for each subscribed event. Verification — every delivery includes an x-mystocks-signature header: HMAC-SHA256(secret, rawBody) hex-encoded. Verify it before processing. Retries — failed deliveries are retried with exponential back-off: up to 6 attempts total (immediate, then 5 s, 30 s, 5 min, 30 min, 2 h). Your endpoint must respond 2xx within 8 seconds or the delivery attempt is marked failed. Delivery semantics — at-least-once. The same event can be delivered more than once (e.g. your endpoint responded slowly and the delivery was retried), and events are not guaranteed to arrive in order. Deduplicate by event id and treat handlers as idempotent.

Parameters

This endpoint has no path or query parameters.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Unique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.

Example: dep_user42_1743152580

Request body

urlstringRequired

HTTPS endpoint that receives POST requests. Must respond 2xx within 8 seconds.

Example: "https://yourapp.com/webhooks/mystocks"

eventsstring[]Required

Event types to subscribe to.

Example: ["trade.settled","deposit.confirmed","kyc.updated"]

secretstring

HMAC-SHA256 signing secret (min 16 chars). MyStocks sends x-mystocks-signature on every delivery.

Example: "my-signing-secret-min-16-chars"

Response fields

idstring

Unique webhook ID.

Example: "wh_abc123"

urlstring

Example: "https://yourapp.com/webhooks/mystocks"

eventsstring[]

Subscribed event types.

statusactive | disabled

Response codes

201Webhook registered.

Request reference

Sandbox available

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/webhooks

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "wh_abc123",
      "description": "Unique webhook ID."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "example": "https://yourapp.com/webhooks/mystocks"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Subscribed event types."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/webhooks' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://yourapp.com/webhooks/mystocks",
  "secret": "whsec_your_signing_secret_at_least_16_chars",
  "events": [
    "order.filled",
    "deposit.confirmed",
    "dividend.paid"
  ]
}'

GET /webhooks

DELETE /webhooks/{id}