Skip to main content

Overview

Webhooks push data to your server as soon as it is published, so you don't have to poll the REST API.

When an event happens, Capital Stake sends an HTTP POST to the URL you registered. The request body is the event payload in JSON.

Channels​

ChannelDeliversPayload
pucarsCorporate announcements filed on PSX through PUCARSPUCARS Announcements

Getting Started​

Webhooks are set up by the Capital Stake team. Request one the same way you request access to the REST and WebSocket APIs, through support at https://csapis.com, and include:

DetailDescription
Endpoint URLAbsolute https:// URL that will receive the POST requests
ChannelThe channel to subscribe to, e.g. pucars
AuthorizationOne of the authorization options below, with its credentials
Signing secretOptional. When set, every request is signed

You can register more than one endpoint on the same channel. Each endpoint receives its own copy of every event.

Request Format​

Every delivery is a POST with the JSON payload as the body. The body is sent exactly as published: there is no wrapper object around it.

Headers​

HeaderValue
Content-Typeapplication/json
User-AgentCapitalStake-Webhooks/1.0
X-CS-ChannelChannel the event was published to, e.g. pucars
X-CS-Webhook-IdID of your webhook registration
X-CS-AttemptDelivery attempt number, starting at 1
X-CS-TimestampUnix time in seconds when the request was sent
X-CS-Signaturesha256=<hex>. Only sent when a signing secret is set

Authorization​

Choose how Capital Stake authenticates to your endpoint. The matching header is added to every request.

TypeHeader sent
None(no header)
BasicAuthorization: Basic <base64 of user:pass>
BearerAuthorization: Bearer <token>
Custom<your header name>: <your value>, e.g. X-Api-Key: abc123

Verifying Signatures​

When a signing secret is set, check every request before trusting it:

  1. Read the X-CS-Timestamp header and the raw request body. Don't parse and re-serialize the body before checking.
  2. Compute HMAC-SHA256(secret, "<X-CS-Timestamp>.<raw body>") and hex-encode it.
  3. Compare sha256=<your result> with X-CS-Signature using a constant-time comparison.
  4. Reject requests whose timestamp is too old (for example, more than 5 minutes) to block replays.
import hashlib, hmac, time

def verify(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
if abs(time.time() - int(timestamp)) > 300:
return False
expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest("sha256=" + expected, signature)
const crypto = require('crypto');

function verify(secret, timestamp, rawBody, signature) {
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
.update(`${timestamp}.`).update(rawBody).digest('hex');
return expected.length === signature.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Responding and Retries​

  • Respond with any 2xx status to confirm receipt.
  • Any other status, a connection error, or no response within 10 seconds counts as a failure.
  • A failed delivery is retried after 5 seconds, up to 3 attempts in total. X-CS-Attempt tells you which attempt you are receiving.
  • After the third failure the event is dropped.

Best Practices​

  1. Respond fast: return 200 straight away and process the event in the background. Slow handlers are treated as failed and receive the event again.
  2. Handle duplicates: a retry can deliver an event you already processed. Use AnnouncementId together with AnnouncementAction to skip events you have already seen.
  3. Verify signatures: set a signing secret and reject requests that fail verification.
  4. Use HTTPS: register an https:// endpoint so payloads and credentials are encrypted in transit.
  5. Don't depend on order: events can arrive out of order, especially after a retry. Use ActionTimestamp to order them.
  6. Backfill gaps: an event that fails three times is not resent. Use the Corporate Announcements REST API to fill in anything your endpoint missed.