Webhooks

Setting Up a Webhook

Navigate to Settings → Webhooks in the SIMOSphere AI dashboard at app.simosphereai.com. Click Add Endpoint and provide the following:

• Endpoint URL — the HTTPS URL that will receive webhook POST requests.
• Events — select which event types to subscribe to (or subscribe to all).
• Secret — a signing secret is generated automatically. Store it securely for signature verification.

Your endpoint must respond with a 2xx status code within 10 seconds. If the endpoint fails, the platform retries delivery with exponential backoff for up to 24 hours (attempts at 1 min, 5 min, 30 min, 2 hours, 12 hours, 24 hours).

Event Types

Each webhook delivery includes a JSON payload with an event field identifying the event type, a timestamp in ISO 8601 format, and a data object with event-specific details.

Payload Format

Every webhook delivery is an HTTP POST with a JSON body. The payload follows a consistent envelope format:

{
  "id": "evt_01J5K8M2N3P4Q5R6S7T8U9V0",
  "event": "usage.threshold_reached",
  "timestamp": "2026-06-06T14:30:00.000Z",
  "data": {
    "threshold": 80,
    "current_usage": 824000,
    "plan_limit": 1000000,
    "period": "2026-06",
    "key_id": "key_abc123"
  }
}

The id field is globally unique and can be used for idempotent processing — if you receive the same event ID twice, you should skip the duplicate.

Signature Verification

Every webhook request includes an X-Simosphere-Signature header containing an HMAC-SHA256 signature of the raw request body. Always verify this signature before processing the event to ensure the request originated from SIMOSphere AI and was not tampered with in transit.

Node.js Verification Example

import crypto from "node:crypto";

function verifyWebhookSignature(
  rawBody: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

// In your Express handler:
app.post("/webhooks/simosphere", (req, res) => {
  const signature = req.headers["x-simosphere-signature"] as string;
  const rawBody = req.body; // must be the raw string, not parsed JSON

  if (!verifyWebhookSignature(rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(rawBody);
  // Process the event...
  res.status(200).json({ received: true });
});

Python Verification Example

import hmac
import hashlib

def verify_webhook_signature(
    raw_body: bytes, signature: str, secret: str
) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your Flask handler:
@app.route("/webhooks/simosphere", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Simosphere-Signature", "")
    if not verify_webhook_signature(request.data, signature, WEBHOOK_SECRET):
        return {"error": "Invalid signature"}, 401

    event = request.get_json()
    # Process the event...
    return {"received": True}, 200

Best Practices