Webhook Integrations

This guide shows how to connect AISentinel to downstream systems through webhooks, including a no-code n8n workflow and a generic signed webhook implementation. Webhooks enable automated responses to policy decisions, audit events, and proof availability.

Event Types

Configuring Webhooks in AISentinel

1. Portal → Integrations → Webhooks.
2. Provide target URL, signing secret, and event filters.
3. Configure retry policy (default exponential backoff up to 24 hours).
4. Optionally enable mutual TLS by uploading your client certificate.

Webhook payloads include:

• id, event, tenant, createdAt
• signature header using HMAC-SHA256 with your shared secret
• auditId for correlation with Auditing & Compliance

Example: n8n Automation

1. Create Webhook Node

• In n8n, add a Webhook trigger node.
• Set the path to /aisentinel/events and method to POST.
• Enable Respond to Webhook with a 200 OK JSON response.

2. Verify Signature

Add a Function node with the following JavaScript to validate the HMAC signature:

const crypto = require('crypto');
const payload = JSON.stringify(items[0].json);
const signature = $json["headers"]["x-aisentinel-signature"];

const digest = crypto
  .createHmac('sha256', $env.AISENTINEL_WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

if (digest !== signature) {
  throw new Error('Signature mismatch');
}
return items;

3. Branch on Event Type

• policy.decision.created: Send Slack alerts for decision = "deny".
• proof.ready: Download proof using the API and archive in SharePoint.
• billing.quota.threshold: Create a Jira ticket for FinOps review.

Refer to the Remediation Automation guide for full incident workflows.

Example: Generic Signed Webhook Receiver (Python FastAPI)

from fastapi import FastAPI, Header, HTTPException, Request
import hmac
import hashlib
import httpx
import os

app = FastAPI()
WEBHOOK_SECRET = os.environ["AISENTINEL_WEBHOOK_SECRET"]

async def verify_signature(payload: bytes, signature: str) -> None:
    digest = hmac.new(WEBHOOK_SECRET.encode(), payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(digest, signature):
        raise HTTPException(status_code=401, detail="invalid_signature")

@app.post("/webhooks/aisentinel")
async def handle_webhook(request: Request, x_aisentinel_signature: str = Header("")):
    body = await request.body()
    await verify_signature(body, x_aisentinel_signature)
    event = await request.json()

    match event["event"]:
        case "policy.decision.created":
            if event["data"]["decision"] == "deny":
                await httpx.post("https://pagerduty.example.com", json={
                    "summary": "AISentinel policy denial",
                    "severity": "high",
                    "source": event["tenant"],
                    "custom_details": event["data"],
                })
        case "proof.ready":
            proof_id = event["data"]["proofId"]
            # Download proof using tenant-scoped API key
        case _:
            pass

    return {"status": "ok"}

Error Handling

• Respond with non-2xx status to trigger retries. AISentinel retries up to 5 times with exponential backoff.
• Inspect retry metadata to distinguish retried deliveries.
• Log event and deliveryId for correlation. Send failures to your SIEM as described in Auditing & Compliance.

Rate Limiting and Backpressure

• AISentinel batches events and respects tenant-level rate limits.
• Use asynchronous handlers or queueing (e.g., AWS SQS, RabbitMQ) to absorb bursts.
• Monitor webhook latency in the portal and alert when above SLA thresholds.

Securing Webhook Endpoints

• Enforce network restrictions (VPC links, IP allowlists).
• Rotate webhook signing secrets regularly using Key Rotation.
• For highly regulated deployments, require mTLS and validate AISentinel client certificates.

Testing

• Use the portal Send Test Event feature to validate connectivity.
• Replay failed events from the delivery history console.
• For local development, use ngrok or cloudflared tunnels with caution and temporary secrets.

Combine webhooks with agent integrations such as LangChain or CrewAI to orchestrate end-to-end remediation and compliance workflows.