Skip to content
MCPShield

Webhook Integration

MCPShield can send scan results to a webhook URL when a monitor detects changes. Supports Discord rich embeds, Slack Block Kit messages, and generic HTTP endpoints.

Supported Webhook Types

Discord

Auto-detected when the URL contains discord.com/api/webhooks. MCPShield sends a rich embed with the grade, score, finding count, status change indicator, and a link to the full report.

Slack

Auto-detected when the URL contains hooks.slack.com. MCPShield sends a Block Kit message with grade, score, findings, status changes, and a “View Full Report” button.

Generic HTTP

Any other URL receives a JSON POST with the scan payload. Useful for custom dashboards, CI/CD integrations, or any HTTP endpoint.

Discord Channel Setup

  1. Open your Discord server and navigate to Server Settings → Integrations → Webhooks.
  2. Click New Webhook. Name it something like “MCPShield Alerts” and select the target channel.
  3. Click Copy Webhook URL.
  4. In MCPShield, create or edit a Monitor and paste the URL into the webhook field.

Discord embeds include: grade badge (color-coded), score, finding count, a “Changed” or “No Changes” status indicator, and a “View Full Report” link.

Slack Channel Setup

  1. Go to api.slack.com/apps and create a new app (or select an existing one).
  2. Navigate to Incoming Webhooks and activate them.
  3. Click Add New Webhook to Workspace and choose the target channel.
  4. Copy the webhook URL (starts with https://hooks.slack.com/services/...).
  5. In MCPShield, create or edit a Monitor and paste the URL into the webhook field.

Slack messages include: a color-coded grade sidebar, score, finding count, a change/stable status indicator, new findings list, and a “View Full Report” button. Signature verification is not used for Slack webhooks.

Payload Format (Generic HTTP)

Non-Discord webhooks receive a JSON POST with this structure:

{
  "event": "monitor.scan_complete",
  "monitor": {
    "id": "mon_abc123",
    "target": "https://github.com/owner/repo",
    "frequency": "daily"
  },
  "scan": {
    "id": "scan_def456",
    "grade": "B",
    "score": 72,
    "totalFindings": 5,
    "reportUrl": "https://www.mcpshield.co/report/scan_def456"
  },
  "changes": {
    "gradeChanged": true,
    "previousGrade": "A",
    "newFindings": 2,
    "removedFindings": 0,
    "toolsChanged": false
  }
}

Signature Verification

If you set a webhook secret on your monitor, MCPShield signs every payload with HMAC-SHA256. The signature is sent in the X-MCPShield-Signature header as a hex string.

Verifying in Node.js

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(body: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

// In your webhook handler:
const sig = req.headers["x-mcpshield-signature"];
const body = await req.text();
if (!sig || !verifySignature(body, sig, YOUR_WEBHOOK_SECRET)) {
  return new Response("Invalid signature", { status: 401 });
}

Discord webhooks do not use signature verification — Discord validates the sender via its own webhook URL format.

TypeScript Interface

interface WebhookPayload {
  event: "monitor.scan_complete";
  monitor: {
    id: string;
    target: string;
    frequency: string;
  };
  scan: {
    id: string;
    grade: string;
    score: number;
    totalFindings: number;
    reportUrl: string;
  };
  changes: {
    gradeChanged: boolean;
    previousGrade: string | null;
    newFindings: number;
    removedFindings: number;
    toolsChanged: boolean;
  };
}
Webhook Integration | MCPShield