Webhooks

Polling tells you when you ask. Webhooks tell you when it happens. Register a URL once and ScripX POSTs you every milestone: match, settlement, payout.

Register

curl -X POST "$BASE_URL/v1/webhooks" \
  -H "X-ScripX-Key: $SCRIPX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/scripx", "event": "*"}'

The response returns your signing_secret (whsec_…) exactly once. Store it like a password; every later view of the webhook is masked. Subscribe to one event or * for all. The current event catalog is in the Webhook events annexure and is also returned live by GET /v1/webhooks.

Every delivery is signed

Each POST carries:

Header	Meaning
`X-ScripX-Signature`	`sha256=<hmac-hex>` over the exact body bytes, keyed by your `whsec_` secret
`X-ScripX-Event`	The event name, e.g. `settlement.settled`
`X-ScripX-Delivery`	Stable delivery id per (event, subscription, entity), your dedupe key
`User-Agent`	`ScripX-Webhooks/1`

Verify before you trust:

import hmac, hashlib

def verify(secret: str, body: bytes, signature: str) -> bool:
    mac = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={mac}", signature)

const crypto = require("crypto");

function verify(secret, rawBody, signature) {
  const mac = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(`sha256=${mac}`), Buffer.from(signature));
}

Sign-check the raw body bytes, before any JSON parsing or re-serialisation. A pretty-printer changes the bytes and the signature stops matching.

Retries and dead-letters

Transient failures (network, 5xx, 429) retry with backoff up to the attempt cap.
Permanent failures (any other 4xx) skip retries and dead-letter immediately.
Exhausted retries dead-letter too.

Nothing is lost: list dead-letters with GET /v1/webhooks/failures and push them again with POST /v1/webhooks/replay. Deliveries can arrive more than once; dedupe on X-ScripX-Delivery.

Receiver rules of thumb

Return 2xx fast; do the work async. Slow receivers look like failures and get retried.
Verify the signature, then dedupe on the delivery id.
Treat the event as a hint and re-read the resource for authoritative state.

Webhook events, the catalog and payload conventions.
Errors, API-side error semantics.

Get started

Concepts

By role

Essentials

Resources

Register

Every delivery is signed

Retries and dead-letters

Receiver rules of thumb

​Register

​Every delivery is signed

​Retries and dead-letters

​Receiver rules of thumb

​Related

Register

Every delivery is signed

Retries and dead-letters

Receiver rules of thumb

Related