Alterscope Developer API

Webhooks push risk events to your endpoint as they happen — an alternative to holding a WebSocket open. Deliveries are signed so you can verify they came from Alterscope.

curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "url": "https://your.app/alterscope-webhook",
       "events": ["peg.depeg.start", "peg.depeg.end", "vault.cap.changed"]
     }' \
  "https://api.alterscope.org/v2/webhooks"

On creation, the response returns a signing_secret (prefix whsec_) exactly once — store it in your secrets manager, because you can’t retrieve it again. You cannot supply your own secret; the platform generates it. Rotate it via POST /v2/webhooks/{id}/rotate-secret. Subscribe to the event types you care about; examples include peg.depeg.start, peg.depeg.end, and vault.cap.changed. See the Event catalog for every type, when it fires, and a sample payload.

Verify the signature

Every delivery includes an Alterscope-Signature header in the form t=<unix_ts>,v1=<hex_hmac_sha256>. The v1 value is the HMAC-SHA256 of "<t>.<raw_body>" (the timestamp, a literal dot, then the raw request body), keyed with your signing_secret. Recompute it, compare in constant time, and reject deliveries whose timestamp is outside a ~5-minute tolerance — that bounds replay attacks:

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance_s: int = 300) -> bool:
    # header looks like: "t=1716902400,v1=abc123..."
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        return False

    # Reject stale timestamps to bound replay.
    if abs(time.time() - int(t)) > tolerance_s:
        return False

    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Reject any delivery whose signature doesn’t match or whose timestamp is stale.

A legacy X-Alterscope-Signature header — a plain HMAC-SHA256 of the raw body (no timestamp prefix) — is dual-emitted alongside Alterscope-Signature during a 60-day transition window and is deprecated. New integrations should verify Alterscope-Signature; migrate any existing checks off the legacy header before the window closes.

Manage subscriptions

Operation	Endpoint
List / create	`GET` / `POST` `/v2/webhooks`
Get / update / delete	`GET` / `PATCH` / `DELETE` `/v2/webhooks/{id}`
Inspect deliveries	`GET /v2/webhooks/{id}/deliveries`
Send a test event	`POST /v2/webhooks/{id}/test`
Rotate the signing secret	`POST /v2/webhooks/{id}/rotate-secret`

After rotating, accept both the old and new signature for a short overlap so in-flight deliveries still verify.

Replay missed events

If your endpoint was down, replay events from the unified feed within your tier’s replay window (see Rate limits):

curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
  "https://api.alterscope.org/v2/events/replay?since_event_id=01J9Z0K3M4N5P6Q7R8S9T0V1W2&limit=100"

Signed webhooks are available on the Team tier and higher; see Rate limits for per-tier limits.

​Subscribe

​Verify the signature

​Manage subscriptions

​Replay missed events

Subscribe

Verify the signature

Manage subscriptions

Replay missed events