Copy page

Resources

Security

Neuratel is designed with security at every layer. This page covers API key security, webhook signature verification, data encryption, and compliance posture.

API Key Security

Scoped Permissions

Every API key can be scoped to specific operations. A key with agents:view scope cannot modify agents — it can only read them. Always create keys with the minimum required scopes.

Create keys in Settings → API Keys with only the scopes each service needs.

Key Rotation

Rotate keys regularly and after any team member departure. Use the Rotate button in Settings → API Keys — the old key stays valid for a configurable grace period while you deploy the new one, then expires automatically.

Storage Best Practices

• Store keys in environment variables or a dedicated secrets manager
• Never commit keys to source control
• Never log or display full key values — Neuratel returns masked_key after creation
• Use separate keys per environment (development, staging, production)
• Use separate keys per service (backend, campaign runner, analytics)

Webhook Signature Verification

Every webhook request from Neuratel includes a cryptographic signature in the X-Webhook-Signature header. Always verify this signature to confirm the request originated from Neuratel and was not tampered with.

How It Works

1. When you create a webhook, Neuratel generates a signing secret (returned once as secret)
2. For each delivery, Neuratel computes HMAC-SHA256(secret, raw_request_body) and sends it in the X-Webhook-Signature header
3. Your server recomputes the HMAC and compares

Python Verification

Code
import hmac
import hashlib
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = "whsec_your_signing_secret"

@app.post("/webhooks/neuratel")
async def handle_webhook(request: Request):
    signature = request.headers.get("X-Webhook-Signature")
    body = await request.body()

    if not signature:
        raise HTTPException(status_code=401, detail="Missing signature")

    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        body,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    payload = await request.json()
    # Process the verified event
    return {"status": "ok"}

JavaScript Verification

Code
const crypto = require("crypto");
const express = require("express");

const app = express();
const WEBHOOK_SECRET = "whsec_your_signing_secret";

app.post(
  "/webhooks/neuratel",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-webhook-signature"];
    const body = req.body;

    if (!signature) {
      return res.status(401).send("Missing signature");
    }

    const expected = crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(body)
      .digest("hex");

    const valid = crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    );

    if (!valid) {
      return res.status(401).send("Invalid signature");
    }

    const payload = JSON.parse(body);
    // Process the verified event
    res.json({ status: "ok" });
  }
);

Timestamp Validation

Neuratel includes a X-Webhook-Timestamp header with each delivery. Use this to reject replayed requests older than a tolerance window (e.g. 5 minutes):

Code
from datetime import datetime, timedelta

timestamp = request.headers.get("X-Webhook-Timestamp")
event_time = datetime.fromisoformat(timestamp)
if datetime.utcnow() - event_time > timedelta(minutes=5):
    raise HTTPException(status_code=401, detail="Request too old")

Rotating Webhook Secrets

If a signing secret is compromised, rotate it immediately:

Code
curl -X POST https://api.neuratel.ai/v1/webhooks/wh_abc123/secret/rotate \
  -H "Authorization: Bearer nk_live_your_api_key"

The old secret is invalidated immediately. Update your webhook handler with the new secret before the next delivery.

Transport Security

• HTTPS only — all API traffic is encrypted in transit via TLS 1.2+. Plaintext HTTP requests are rejected
• Webhook delivery — Neuratel only delivers webhooks to https:// URLs
• Certificate validation — Neuratel validates your webhook endpoint's TLS certificate. Self-signed certificates are not accepted

Data Encryption

• In transit — TLS 1.2+ for all API communication and webhook deliveries
• At rest — call recordings, transcripts, and knowledge base documents are encrypted at rest using AES-256
• Provider credentials — BYOK API keys stored with envelope encryption. Keys are never returned in plaintext after initial creation

Compliance

SOC 2 Type II

Neuratel's SOC 2 Type II audit is in progress. Contact [email protected] for the latest status and to request the report when available.

GDPR

• Data residency — choose US or EU data region during onboarding
• Data deletion — request deletion of any user data via API or by emailing [email protected]
• Data retention — configurable per organization. See Organization Management for retention settings
• Data portability — export call logs, transcripts, and recordings via API

Call Recording Consent

Recording laws vary by jurisdiction. Common requirements:

Jurisdiction	Consent Model	Requirement
US (Federal)	One-party	One participant must consent
California, Florida, etc.	Two-party	All participants must consent
EU (GDPR)	Explicit	Clear consent required, purpose stated
UK	Informed	Caller must be informed

If you enable call recording, configure your agent's first_message to include a consent notice:

Code
"This call may be recorded for quality and training purposes. Do you consent to continue?"

Incident Response

If you suspect a security incident related to your Neuratel account:

1. Rotate all API keys immediately — use Settings → API Keys → Rotate in the dashboard
2. Rotate webhook secrets — POST /v1/webhooks/{id}/secret/rotate
3. Contact [email protected] with the details and affected request_id values
4. Review API key access logs — check last_used_at on all keys

Security Contact

Report vulnerabilities or security concerns to [email protected]. We acknowledge reports within 24 hours and provide status updates within 72 hours.

Next Steps

• Using API Keys — create and rotate scoped keys
• Webhooks — full webhook integration guide
• Error Codes — understand authentication errors