Webhooks
Register an HTTPS endpoint and every event on the entities your watchlists follow is POSTed to it, signed. The same events are in the polling feed, GET /v1/events.
Register an endpoint
POST /v1/webhooks { "url": "https://hooks.example.com/sisoco", "event_types": [] }
event_types empty means every type your account can use. The answer holds the signing secret (whsec_…), shown once: store it. POST /v1/webhooks/{id}/test sends one signed sample event (header Sisoco-Test: true, event_id starting evt_test_); GET /v1/webhooks/{id}/deliveries is the delivery log.
Endpoint rules. https:// only, port 443, a public DNS name. Every address the name resolves to must be public, checked at registration and before every delivery. Redirects are not followed: answer 2xx directly.
Delivery. At least once. A failed delivery is retried with exponential back-off (1, 2, 4, 8 … minutes, at most 6 hours apart) for 24 hours. Dedupe on event_id. Answer within 10 seconds and do the work afterwards. An endpoint that fails for 24 hours is disabled and the account is emailed; the events stay in the feed.
Version. Bodies are rendered in your account's pinned API version, given in the Sisoco-Version header and the api_version field.
Headers
| Header | Value |
|---|---|
Sisoco-Signature |
t=<unix seconds>,v1=<hex HMAC-SHA256> |
Sisoco-Event-Id |
the event's event_id |
Sisoco-Delivery-Id |
this delivery (the same on every retry) |
Sisoco-Version |
API version of the body |
Verify the signature
The signature is HMAC-SHA256 with the endpoint secret over <t>.<raw request body>. Use the raw body bytes as received, before any JSON parsing; compare in constant time; reject timestamps outside your tolerance (5 minutes here) to stop replays.
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
/**
* true when `signatureHeader` (the Sisoco-Signature header) was made with
* `secret` over `rawBody` (a string or Buffer of the exact bytes received)
* within `toleranceSeconds` of now.
*/
export function verifySisocoSignature(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
String(signatureHeader)
.split(',')
.map((p) => p.trim().split('=', 2)),
);
const t = Number(parts.t);
if (!Number.isInteger(t) || !parts.v1) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;
const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
const a = Buffer.from(expected, 'utf8');
const b = Buffer.from(parts.v1, 'utf8');
return a.length === b.length && timingSafeEqual(a, b);
}
Python
import hmac, hashlib, time
def verify_sisoco_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.strip().split("=", 1) for p in header.split(","))
t = int(parts.get("t", "0"))
if abs(time.time() - t) > tolerance or "v1" not in parts:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Event shape
Every body is one event: event_id, type, severity (after your watchlist's profile), entity, effective_at, observed_at, source (id, record URL, attribution), data, plus watchlist_id and client_reference. Each type and its data is in the events reference.