Sisoco Oneby Sisoco Partners

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.