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
| Channel | Delivers | Payload |
|---|---|---|
pucars | Corporate announcements filed on PSX through PUCARS | PUCARS 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:
| Detail | Description |
|---|---|
| Endpoint URL | Absolute https:// URL that will receive the POST requests |
| Channel | The channel to subscribe to, e.g. pucars |
| Authorization | One of the authorization options below, with its credentials |
| Signing secret | Optional. 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
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | CapitalStake-Webhooks/1.0 |
X-CS-Channel | Channel the event was published to, e.g. pucars |
X-CS-Webhook-Id | ID of your webhook registration |
X-CS-Attempt | Delivery attempt number, starting at 1 |
X-CS-Timestamp | Unix time in seconds when the request was sent |
X-CS-Signature | sha256=<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.
| Type | Header sent |
|---|---|
| None | (no header) |
| Basic | Authorization: Basic <base64 of user:pass> |
| Bearer | Authorization: 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:
- Read the
X-CS-Timestampheader and the raw request body. Don't parse and re-serialize the body before checking. - Compute
HMAC-SHA256(secret, "<X-CS-Timestamp>.<raw body>")and hex-encode it. - Compare
sha256=<your result>withX-CS-Signatureusing a constant-time comparison. - 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
2xxstatus 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-Attempttells you which attempt you are receiving. - After the third failure the event is dropped.
Best Practices
- Respond fast: return
200straight away and process the event in the background. Slow handlers are treated as failed and receive the event again. - Handle duplicates: a retry can deliver an event you already processed. Use
AnnouncementIdtogether withAnnouncementActionto skip events you have already seen. - Verify signatures: set a signing secret and reject requests that fail verification.
- Use HTTPS: register an
https://endpoint so payloads and credentials are encrypted in transit. - Don't depend on order: events can arrive out of order, especially after a retry. Use
ActionTimestampto order them. - Backfill gaps: an event that fails three times is not resent. Use the Corporate Announcements REST API to fill in anything your endpoint missed.