Subscribing to Events via Webhooks

AltScore allows you to subscribe to events occurring on the platform via Webhooks. Delivery is handled by Svix, which gives you a cryptographic signature on every send, automatic retries and, above all, visibility: you can now see whether an event reached your endpoint and retry it if it failed.

Configuring your webhooks from the hub

The recommended way to manage webhooks is from the AltScore hub, under Settings > Webhooks. There you will find the webhooks portal, where you can:

• Register an endpoint and choose which events it subscribes to.
• See the delivery history for each endpoint, with every attempt, your server's response and the payload that was sent.
• Manually retry any message that failed, without having to ask support.
• Look up each endpoint's signing secret, which you need in order to verify deliveries.
• Send test messages to your endpoint while you build it.

Verifying the signature

Always verify the signature before processing the request body. Without this, anyone who knows your endpoint URL can send you a forged POST and your system will treat it as a legitimate AltScore event.

Every delivery includes three headers:

The signing secret is specific to each endpoint and you get it from Settings > Webhooks. It starts with the whsec_ prefix.

Using the Svix libraries

This is the recommended approach: beyond checking the signature, these libraries automatically reject messages whose svix-timestamp is more than five minutes away from the current time, in the past or the future, which protects you against replay attacks.

pip install svix

from fastapi import FastAPI, Request, HTTPException
from svix.webhooks import Webhook, WebhookVerificationError
 
app = FastAPI()
WEBHOOK_SECRET = "whsec_..."  # Settings > Webhooks
 
@app.post("/webhooks/altscore")
async def handle_altscore_webhook(request: Request):
    payload = await request.body()
    try:
        event = Webhook(WEBHOOK_SECRET).verify(payload, dict(request.headers))
    except WebhookVerificationError:
        raise HTTPException(status_code=401, detail="Invalid signature")
 
    if event["event"] == "bc.execution.completed":
        execution = event["data"]["entity"]
        ...
 
    return {"status": "received"}

Verifying manually

If you would rather not add a dependency, the procedure is:

1. Build the signed content by concatenating {svix-id}.{svix-timestamp}.{body}.
2. Base64-decode the portion of the secret that follows whsec_.
3. Compute an HMAC with SHA-256 over the signed content using that secret, and base64-encode the result.
4. Compare that result against each signature in svix-signature, first stripping the version prefix (v1,). The header may carry several space-delimited signatures; a match on any one of them is enough.
5. Check that svix-timestamp is within your tolerance of your server's clock, to rule out replays.

Use a constant-time comparison (for example hmac.compare_digest in Python) to prevent timing attacks. If you verify manually, your server needs its clock synchronized via NTP.

Retries and delivery

If your endpoint does not respond, Svix retries automatically with increasing backoff. The attempt schedule is:

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (in addition to the previous)

A delivery counts as successful when your endpoint responds with a 2xx status code within 15 seconds. Any other response, including redirects, counts as a failure. Once the attempts are exhausted, the message is marked as failed and you can retry it by hand from Settings > Webhooks.

If every delivery to an endpoint fails for 5 consecutive days, the endpoint is disabled automatically.

Respond quickly: accept the event, queue it and process it afterwards. If you do the heavy work before responding, you may exceed 15 seconds and trigger retries of an event you already processed.

Managing webhooks via API

Everything available in the hub has an API equivalent, documented in Webhooks API. The structure of the event you receive is described in Events.