@zyphr-dev/mcp-server 0.1.0

package/src/integration/quickstart/webhook.ts

@@ -0,0 +1,664 @@
+import type { QuickstartChannelMap } from '../quickstart-types.js';
+
+const DOCS = 'https://docs.zyphr.dev/features/webhooks-security';
+
+const ENV: string[] = ['ZYPHR_WEBHOOK_SECRET'];
+
+const NEXT_STEPS = [
+  'Add ZYPHR_WEBHOOK_SECRET to your .env file — get it from `zyphr.webhooks.rotateWebhookSecret(id)` or the Zyphr dashboard.',
+  'Configure the webhook endpoint URL in the Zyphr dashboard or via `create_webhook`.',
+  'ALWAYS verify signatures before processing payloads — never trust an unverified webhook.',
+  'Reject deliveries whose timestamp is more than 5 minutes from now to prevent replay attacks.',
+];
+
+export const webhookChannel: QuickstartChannelMap = {
+  node: {
+    sdk: {
+      channel: 'webhook',
+      language: 'node',
+      framework: null,
+      variant: 'webhook-handler',
+      files: [
+        {
+          path: 'src/lib/verifyZyphrWebhook.ts',
+          purpose:
+            'Standard Webhooks (HMAC-SHA256) signature + timestamp verification. Mirrors the canonical snippet in apps/docs/docs/features/webhooks-security.md.',
+          contents:
+            "import crypto from 'crypto';\n\n" +
+            'export function verifyZyphrWebhook(\n' +
+            '  payload: string,\n' +
+            "  headers: { 'webhook-id': string; 'webhook-timestamp': string; 'webhook-signature': string },\n" +
+            '  secret: string,\n' +
+            '): boolean {\n' +
+            "  const msgId = headers['webhook-id'];\n" +
+            "  const timestamp = parseInt(headers['webhook-timestamp'], 10);\n" +
+            "  const signatures = headers['webhook-signature'];\n\n" +
+            '  const now = Math.floor(Date.now() / 1000);\n' +
+            '  if (Math.abs(now - timestamp) > 300) return false;\n\n' +
+            '  const signedContent = `${msgId}.${timestamp}.${payload}`;\n' +
+            '  const secretBytes = Buffer.from(\n' +
+            "    secret.startsWith('whsec_') ? secret.slice(6) : secret,\n" +
+            "    'hex',\n" +
+            '  );\n' +
+            '  const expected = crypto\n' +
+            "    .createHmac('sha256', secretBytes)\n" +
+            '    .update(signedContent)\n' +
+            "    .digest('base64');\n\n" +
+            "  for (const sig of signatures.split(' ')) {\n" +
+            '    const sigValue = sig.slice(3);\n' +
+            '    if (\n' +
+            '      sigValue.length === expected.length &&\n' +
+            '      crypto.timingSafeEqual(Buffer.from(sigValue), Buffer.from(expected))\n' +
+            '    ) {\n' +
+            '      return true;\n' +
+            '    }\n' +
+            '  }\n' +
+            '  return false;\n' +
+            '}\n',
+          overwrite: false,
+        },
+      ],
+      envVarsNeeded: ENV,
+      nextSteps: NEXT_STEPS,
+      docsUrl: DOCS,
+    },
+    frameworks: {
+      express: {
+        channel: 'webhook',
+        language: 'node',
+        framework: 'express',
+        variant: 'webhook-handler',
+        files: [
+          {
+            path: 'src/lib/verifyZyphrWebhook.ts',
+            purpose: 'Standard Webhooks signature verification helper',
+            contents:
+              "import crypto from 'crypto';\n\n" +
+              'export function verifyZyphrWebhook(payload: string, headers: Record<string,string>, secret: string): boolean {\n' +
+              "  const msgId = headers['webhook-id'];\n" +
+              "  const timestamp = parseInt(headers['webhook-timestamp'], 10);\n" +
+              "  const signatures = headers['webhook-signature'] || '';\n" +
+              '  const now = Math.floor(Date.now() / 1000);\n' +
+              '  if (Math.abs(now - timestamp) > 300) return false;\n' +
+              '  const signedContent = `${msgId}.${timestamp}.${payload}`;\n' +
+              "  const secretBytes = Buffer.from(secret.startsWith('whsec_') ? secret.slice(6) : secret, 'hex');\n" +
+              "  const expected = crypto.createHmac('sha256', secretBytes).update(signedContent).digest('base64');\n" +
+              "  return signatures.split(' ').some((sig) => {\n" +
+              '    const v = sig.slice(3);\n' +
+              '    return v.length === expected.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected));\n' +
+              '  });\n' +
+              '}\n',
+            overwrite: false,
+          },
+          {
+            path: 'src/routes/zyphrWebhook.ts',
+            purpose:
+              'Express route that VERIFIES the signature before processing the webhook. Uses express.raw() so we can hash the exact bytes.',
+            contents:
+              "import { Router, raw } from 'express';\n" +
+              "import { verifyZyphrWebhook } from '../lib/verifyZyphrWebhook.js';\n\n" +
+              'export const zyphrWebhookRouter = Router();\n\n' +
+              "zyphrWebhookRouter.post('/zyphr', raw({ type: 'application/json' }), (req, res) => {\n" +
+              '  const payload = (req.body as Buffer).toString();\n' +
+              '  const headers = req.headers as Record<string, string>;\n' +
+              '  if (!verifyZyphrWebhook(payload, headers, process.env.ZYPHR_WEBHOOK_SECRET!)) {\n' +
+              "    return res.status(401).send('invalid signature');\n" +
+              '  }\n' +
+              '  const event = JSON.parse(payload) as { type: string; data: unknown };\n' +
+              "  console.log('zyphr event', event.type);\n" +
+              '  res.sendStatus(204);\n' +
+              '});\n',
+            overwrite: false,
+          },
+        ],
+        envVarsNeeded: ENV,
+        nextSteps: [
+          ...NEXT_STEPS,
+          'Mount the router BEFORE express.json(): app.use(zyphrWebhookRouter)',
+        ],
+        docsUrl: DOCS,
+      },
+      nextjs: {
+        channel: 'webhook',
+        language: 'node',
+        framework: 'nextjs',
+        variant: 'webhook-handler',
+        files: [
+          {
+            path: 'src/lib/verifyZyphrWebhook.ts',
+            purpose: 'Standard Webhooks signature verification helper',
+            contents:
+              "import crypto from 'crypto';\n\n" +
+              'export function verifyZyphrWebhook(payload: string, headers: Headers, secret: string): boolean {\n' +
+              "  const msgId = headers.get('webhook-id') || '';\n" +
+              "  const timestamp = parseInt(headers.get('webhook-timestamp') || '0', 10);\n" +
+              "  const signatures = headers.get('webhook-signature') || '';\n" +
+              '  const now = Math.floor(Date.now() / 1000);\n' +
+              '  if (Math.abs(now - timestamp) > 300) return false;\n' +
+              '  const signedContent = `${msgId}.${timestamp}.${payload}`;\n' +
+              "  const secretBytes = Buffer.from(secret.startsWith('whsec_') ? secret.slice(6) : secret, 'hex');\n" +
+              "  const expected = crypto.createHmac('sha256', secretBytes).update(signedContent).digest('base64');\n" +
+              "  return signatures.split(' ').some((sig) => {\n" +
+              '    const v = sig.slice(3);\n' +
+              '    return v.length === expected.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected));\n' +
+              '  });\n' +
+              '}\n',
+            overwrite: false,
+          },
+          {
+            path: 'src/app/api/zyphr/webhook/route.ts',
+            purpose: 'Next.js App Router webhook handler with signature verification',
+            contents:
+              "import { NextResponse } from 'next/server';\n" +
+              "import { verifyZyphrWebhook } from '@/lib/verifyZyphrWebhook';\n\n" +
+              'export async function POST(req: Request) {\n' +
+              '  const payload = await req.text();\n' +
+              '  if (!verifyZyphrWebhook(payload, req.headers, process.env.ZYPHR_WEBHOOK_SECRET!)) {\n' +
+              "    return new NextResponse('invalid signature', { status: 401 });\n" +
+              '  }\n' +
+              '  const event = JSON.parse(payload) as { type: string; data: unknown };\n' +
+              "  console.log('zyphr event', event.type);\n" +
+              '  return new NextResponse(null, { status: 204 });\n' +
+              '}\n',
+            overwrite: false,
+          },
+        ],
+        envVarsNeeded: ENV,
+        nextSteps: NEXT_STEPS,
+        docsUrl: DOCS,
+      },
+    },
+  },
+  python: {
+    sdk: {
+      channel: 'webhook',
+      language: 'python',
+      framework: null,
+      variant: 'webhook-handler',
+      files: [
+        {
+          path: 'app/zyphr_webhook.py',
+          purpose: 'Standard Webhooks signature verification helper (verbatim from docs)',
+          contents:
+            'import hashlib\n' +
+            'import hmac\n' +
+            'import base64\n' +
+            'import time\n\n' +
+            'def verify_zyphr_webhook(payload: str, headers: dict, secret: str) -> bool:\n' +
+            '    msg_id = headers.get("webhook-id", "")\n' +
+            '    timestamp = headers.get("webhook-timestamp", "")\n' +
+            '    signature = headers.get("webhook-signature", "")\n\n' +
+            '    now = int(time.time())\n' +
+            '    if abs(now - int(timestamp)) > 300:\n' +
+            '        return False\n\n' +
+            '    signed_content = f"{msg_id}.{timestamp}.{payload}"\n' +
+            '    secret_hex = secret.removeprefix("whsec_")\n' +
+            '    secret_bytes = bytes.fromhex(secret_hex)\n' +
+            '    expected = base64.b64encode(\n' +
+            '        hmac.new(secret_bytes, signed_content.encode(), hashlib.sha256).digest()\n' +
+            '    ).decode()\n\n' +
+            '    for sig in signature.split(" "):\n' +
+            '        sig_value = sig.removeprefix("v1,")\n' +
+            '        if hmac.compare_digest(sig_value, expected):\n' +
+            '            return True\n' +
+            '    return False\n',
+          overwrite: false,
+        },
+      ],
+      envVarsNeeded: ENV,
+      nextSteps: NEXT_STEPS,
+      docsUrl: DOCS,
+    },
+    frameworks: {
+      flask: {
+        channel: 'webhook',
+        language: 'python',
+        framework: 'flask',
+        variant: 'webhook-handler',
+        files: [
+          {
+            path: 'app/zyphr_webhook.py',
+            purpose: 'Standard Webhooks signature verification helper',
+            contents:
+              'import hashlib, hmac, base64, time\n\n' +
+              'def verify_zyphr_webhook(payload: str, headers, secret: str) -> bool:\n' +
+              '    msg_id = headers.get("webhook-id", "")\n' +
+              '    timestamp = headers.get("webhook-timestamp", "")\n' +
+              '    signature = headers.get("webhook-signature", "")\n' +
+              '    if abs(int(time.time()) - int(timestamp)) > 300:\n' +
+              '        return False\n' +
+              '    signed = f"{msg_id}.{timestamp}.{payload}"\n' +
+              '    secret_bytes = bytes.fromhex(secret.removeprefix("whsec_"))\n' +
+              '    expected = base64.b64encode(hmac.new(secret_bytes, signed.encode(), hashlib.sha256).digest()).decode()\n' +
+              '    return any(hmac.compare_digest(sig.removeprefix("v1,"), expected) for sig in signature.split(" "))\n',
+            overwrite: false,
+          },
+          {
+            path: 'app/routes/zyphr_webhook.py',
+            purpose: 'Flask blueprint that verifies the webhook signature before processing',
+            contents:
+              'import os, json\n' +
+              'from flask import Blueprint, request, abort\n' +
+              'from ..zyphr_webhook import verify_zyphr_webhook\n\n' +
+              'zyphr_webhook_bp = Blueprint("zyphr_webhook", __name__)\n\n' +
+              '@zyphr_webhook_bp.route("/webhooks/zyphr", methods=["POST"])\n' +
+              'def handle():\n' +
+              '    payload = request.get_data(as_text=True)\n' +
+              '    if not verify_zyphr_webhook(payload, request.headers, os.environ["ZYPHR_WEBHOOK_SECRET"]):\n' +
+              '        abort(401, "invalid signature")\n' +
+              '    event = json.loads(payload)\n' +
+              '    print("zyphr event", event.get("type"))\n' +
+              '    return "", 204\n',
+            overwrite: false,
+          },
+        ],
+        envVarsNeeded: ENV,
+        nextSteps: NEXT_STEPS,
+        docsUrl: DOCS,
+      },
+      fastapi: {
+        channel: 'webhook',
+        language: 'python',
+        framework: 'fastapi',
+        variant: 'webhook-handler',
+        files: [
+          {
+            path: 'app/routers/zyphr_webhook.py',
+            purpose: 'FastAPI router that verifies the webhook signature before processing',
+            contents:
+              'import os, json, hashlib, hmac, base64, time\n' +
+              'from fastapi import APIRouter, Request, HTTPException\n\n' +
+              'router = APIRouter()\n\n' +
+              'def verify_zyphr_webhook(payload: str, headers, secret: str) -> bool:\n' +
+              '    msg_id = headers.get("webhook-id", "")\n' +
+              '    timestamp = headers.get("webhook-timestamp", "")\n' +
+              '    signature = headers.get("webhook-signature", "")\n' +
+              '    if abs(int(time.time()) - int(timestamp)) > 300:\n' +
+              '        return False\n' +
+              '    signed = f"{msg_id}.{timestamp}.{payload}"\n' +
+              '    secret_bytes = bytes.fromhex(secret.removeprefix("whsec_"))\n' +
+              '    expected = base64.b64encode(hmac.new(secret_bytes, signed.encode(), hashlib.sha256).digest()).decode()\n' +
+              '    return any(hmac.compare_digest(sig.removeprefix("v1,"), expected) for sig in signature.split(" "))\n\n' +
+              '@router.post("/webhooks/zyphr")\n' +
+              'async def handle(request: Request):\n' +
+              '    body = (await request.body()).decode()\n' +
+              '    if not verify_zyphr_webhook(body, request.headers, os.environ["ZYPHR_WEBHOOK_SECRET"]):\n' +
+              '        raise HTTPException(status_code=401, detail="invalid signature")\n' +
+              '    event = json.loads(body)\n' +
+              '    print("zyphr event", event.get("type"))\n' +
+              '    return {"ok": True}\n',
+            overwrite: false,
+          },
+        ],
+        envVarsNeeded: ENV,
+        nextSteps: NEXT_STEPS,
+        docsUrl: DOCS,
+      },
+    },
+  },
+  ruby: {
+    sdk: {
+      channel: 'webhook',
+      language: 'ruby',
+      framework: null,
+      variant: 'webhook-handler',
+      files: [
+        {
+          path: 'app/services/zyphr_webhook.rb',
+          purpose: 'Standard Webhooks signature verification helper',
+          contents:
+            "require 'openssl'\n" +
+            "require 'base64'\n\n" +
+            'class ZyphrWebhook\n' +
+            '  def self.verify(payload:, headers:, secret:)\n' +
+            "    msg_id = headers['webhook-id'].to_s\n" +
+            "    timestamp = headers['webhook-timestamp'].to_i\n" +
+            "    signatures = headers['webhook-signature'].to_s\n\n" +
+            '    return false if (Time.now.to_i - timestamp).abs > 300\n\n' +
+            '    signed = "#{msg_id}.#{timestamp}.#{payload}"\n' +
+            "    hex = secret.start_with?('whsec_') ? secret[6..] : secret\n" +
+            '    secret_bytes = [hex].pack(\'H*\')\n' +
+            "    expected = Base64.strict_encode64(OpenSSL::HMAC.digest('SHA256', secret_bytes, signed))\n\n" +
+            "    signatures.split(' ').any? do |sig|\n" +
+            '      v = sig[3..]\n' +
+            '      v && Rack::Utils.secure_compare(v, expected)\n' +
+            '    end\n' +
+            '  end\n' +
+            'end\n',
+          overwrite: false,
+        },
+      ],
+      envVarsNeeded: ENV,
+      nextSteps: NEXT_STEPS,
+      docsUrl: DOCS,
+    },
+    frameworks: {
+      rails: {
+        channel: 'webhook',
+        language: 'ruby',
+        framework: 'rails',
+        variant: 'webhook-handler',
+        files: [
+          {
+            path: 'app/services/zyphr_webhook.rb',
+            purpose: 'Standard Webhooks signature verification helper',
+            contents:
+              "require 'openssl'\n" +
+              "require 'base64'\n\n" +
+              'class ZyphrWebhook\n' +
+              '  def self.verify(payload:, headers:, secret:)\n' +
+              "    msg_id = headers['webhook-id'].to_s\n" +
+              "    timestamp = headers['webhook-timestamp'].to_i\n" +
+              "    signatures = headers['webhook-signature'].to_s\n" +
+              '    return false if (Time.now.to_i - timestamp).abs > 300\n' +
+              '    signed = "#{msg_id}.#{timestamp}.#{payload}"\n' +
+              "    hex = secret.start_with?('whsec_') ? secret[6..] : secret\n" +
+              '    secret_bytes = [hex].pack(\'H*\')\n' +
+              "    expected = Base64.strict_encode64(OpenSSL::HMAC.digest('SHA256', secret_bytes, signed))\n" +
+              "    signatures.split(' ').any? { |sig| sig[3..] && ActiveSupport::SecurityUtils.secure_compare(sig[3..], expected) }\n" +
+              '  end\n' +
+              'end\n',
+            overwrite: false,
+          },
+          {
+            path: 'app/controllers/zyphr_webhooks_controller.rb',
+            purpose: 'Rails controller that verifies the webhook signature before processing',
+            contents:
+              'class ZyphrWebhooksController < ApplicationController\n' +
+              '  skip_before_action :verify_authenticity_token\n\n' +
+              '  def create\n' +
+              "    payload = request.raw_post\n" +
+              "    secret = ENV.fetch('ZYPHR_WEBHOOK_SECRET')\n" +
+              '    unless ZyphrWebhook.verify(payload: payload, headers: request.headers, secret: secret)\n' +
+              '      head :unauthorized and return\n' +
+              '    end\n' +
+              '    event = JSON.parse(payload)\n' +
+              "    Rails.logger.info(\"zyphr event #{event['type']}\")\n" +
+              '    head :no_content\n' +
+              '  end\n' +
+              'end\n',
+            overwrite: false,
+          },
+        ],
+        envVarsNeeded: ENV,
+        nextSteps: [
+          ...NEXT_STEPS,
+          "Add route: post '/webhooks/zyphr', to: 'zyphr_webhooks#create'",
+        ],
+        docsUrl: DOCS,
+      },
+    },
+  },
+  go: {
+    sdk: {
+      channel: 'webhook',
+      language: 'go',
+      framework: null,
+      variant: 'webhook-handler',
+      files: [
+        {
+          path: 'internal/zyphr/verify.go',
+          purpose:
+            'Standard Webhooks signature verification helper (verbatim from docs).',
+          contents:
+            'package zyphr\n\n' +
+            'import (\n' +
+            '\t"crypto/hmac"\n' +
+            '\t"crypto/sha256"\n' +
+            '\t"encoding/base64"\n' +
+            '\t"encoding/hex"\n' +
+            '\t"math"\n' +
+            '\t"strconv"\n' +
+            '\t"strings"\n' +
+            '\t"time"\n' +
+            ')\n\n' +
+            'func VerifyWebhook(payload, msgID, timestamp, signature, secret string) bool {\n' +
+            '\tts, err := strconv.ParseInt(timestamp, 10, 64)\n' +
+            '\tif err != nil { return false }\n' +
+            '\tif math.Abs(float64(time.Now().Unix()-ts)) > 300 { return false }\n\n' +
+            '\tsigned := msgID + "." + timestamp + "." + payload\n' +
+            '\tsecretHex := strings.TrimPrefix(secret, "whsec_")\n' +
+            '\tsecretBytes, err := hex.DecodeString(secretHex)\n' +
+            '\tif err != nil { return false }\n' +
+            '\tmac := hmac.New(sha256.New, secretBytes)\n' +
+            '\tmac.Write([]byte(signed))\n' +
+            '\texpected := base64.StdEncoding.EncodeToString(mac.Sum(nil))\n\n' +
+            '\tfor _, sig := range strings.Split(signature, " ") {\n' +
+            '\t\tv := strings.TrimPrefix(sig, "v1,")\n' +
+            '\t\tif hmac.Equal([]byte(v), []byte(expected)) { return true }\n' +
+            '\t}\n' +
+            '\treturn false\n' +
+            '}\n',
+          overwrite: false,
+        },
+      ],
+      envVarsNeeded: ENV,
+      nextSteps: NEXT_STEPS,
+      docsUrl: DOCS,
+    },
+  },
+  php: {
+    sdk: {
+      channel: 'webhook',
+      language: 'php',
+      framework: null,
+      variant: 'webhook-handler',
+      files: [
+        {
+          path: 'app/Webhooks/ZyphrWebhook.php',
+          purpose: 'Standard Webhooks signature verification helper (verbatim from docs)',
+          contents:
+            '<?php\n\n' +
+            'namespace App\\Webhooks;\n\n' +
+            'class ZyphrWebhook\n' +
+            '{\n' +
+            '    public static function verify(string $payload, array $headers, string $secret): bool\n' +
+            '    {\n' +
+            "        $msgId = $headers['webhook-id'] ?? '';\n" +
+            "        $timestamp = $headers['webhook-timestamp'] ?? '';\n" +
+            "        $signature = $headers['webhook-signature'] ?? '';\n" +
+            '        if (abs(time() - intval($timestamp)) > 300) {\n' +
+            '            return false;\n' +
+            '        }\n' +
+            '        $signed = "{$msgId}.{$timestamp}.{$payload}";\n' +
+            "        $hex = str_starts_with($secret, 'whsec_') ? substr($secret, 6) : $secret;\n" +
+            "        $expected = base64_encode(hash_hmac('sha256', $signed, hex2bin($hex), true));\n" +
+            "        foreach (explode(' ', $signature) as $sig) {\n" +
+            '            if (hash_equals(substr($sig, 3), $expected)) {\n' +
+            '                return true;\n' +
+            '            }\n' +
+            '        }\n' +
+            '        return false;\n' +
+            '    }\n' +
+            '}\n',
+          overwrite: false,
+        },
+      ],
+      envVarsNeeded: ENV,
+      nextSteps: NEXT_STEPS,
+      docsUrl: DOCS,
+    },
+    frameworks: {
+      laravel: {
+        channel: 'webhook',
+        language: 'php',
+        framework: 'laravel',
+        variant: 'webhook-handler',
+        files: [
+          {
+            path: 'app/Webhooks/ZyphrWebhook.php',
+            purpose: 'Standard Webhooks signature verification helper',
+            contents:
+              '<?php\n\n' +
+              'namespace App\\Webhooks;\n\n' +
+              'class ZyphrWebhook\n' +
+              '{\n' +
+              '    public static function verify(string $payload, array $headers, string $secret): bool\n' +
+              '    {\n' +
+              "        $msgId = $headers['webhook-id'][0] ?? '';\n" +
+              "        $timestamp = $headers['webhook-timestamp'][0] ?? '';\n" +
+              "        $signature = $headers['webhook-signature'][0] ?? '';\n" +
+              '        if (abs(time() - intval($timestamp)) > 300) {\n' +
+              '            return false;\n' +
+              '        }\n' +
+              '        $signed = "{$msgId}.{$timestamp}.{$payload}";\n' +
+              "        $hex = str_starts_with($secret, 'whsec_') ? substr($secret, 6) : $secret;\n" +
+              "        $expected = base64_encode(hash_hmac('sha256', $signed, hex2bin($hex), true));\n" +
+              "        foreach (explode(' ', $signature) as $sig) {\n" +
+              '            if (hash_equals(substr($sig, 3), $expected)) {\n' +
+              '                return true;\n' +
+              '            }\n' +
+              '        }\n' +
+              '        return false;\n' +
+              '    }\n' +
+              '}\n',
+            overwrite: false,
+          },
+          {
+            path: 'app/Http/Controllers/ZyphrWebhookController.php',
+            purpose: 'Laravel controller that verifies the webhook signature before processing',
+            contents:
+              '<?php\n\n' +
+              'namespace App\\Http\\Controllers;\n\n' +
+              'use App\\Webhooks\\ZyphrWebhook;\n' +
+              'use Illuminate\\Http\\Request;\n\n' +
+              'class ZyphrWebhookController extends Controller\n' +
+              '{\n' +
+              '    public function handle(Request $request)\n' +
+              '    {\n' +
+              "        $payload = $request->getContent();\n" +
+              "        $secret = config('services.zyphr.webhook_secret');\n" +
+              "        if (! ZyphrWebhook::verify($payload, $request->headers->all(), $secret)) {\n" +
+              "            return response('invalid signature', 401);\n" +
+              '        }\n' +
+              "        $event = json_decode($payload, true);\n" +
+              "        \\Log::info('zyphr event ' . ($event['type'] ?? 'unknown'));\n" +
+              "        return response()->noContent();\n" +
+              '    }\n' +
+              '}\n',
+            overwrite: false,
+          },
+        ],
+        envVarsNeeded: ENV,
+        nextSteps: [
+          ...NEXT_STEPS,
+          "Register route in routes/api.php: Route::post('/webhooks/zyphr', [ZyphrWebhookController::class, 'handle']);",
+          "Exclude this route from CSRF (VerifyCsrfToken::$except).",
+        ],
+        docsUrl: DOCS,
+      },
+    },
+  },
+  csharp: {
+    sdk: {
+      channel: 'webhook',
+      language: 'csharp',
+      framework: null,
+      variant: 'webhook-handler',
+      files: [
+        {
+          path: 'Webhooks/ZyphrWebhookVerifier.cs',
+          purpose: 'Standard Webhooks signature verification helper',
+          contents:
+            'using System.Security.Cryptography;\n' +
+            'using System.Text;\n\n' +
+            'namespace YourApp.Webhooks;\n\n' +
+            'public static class ZyphrWebhookVerifier\n' +
+            '{\n' +
+            '    public static bool Verify(string payload, IDictionary<string,string> headers, string secret)\n' +
+            '    {\n' +
+            '        var msgId = headers.TryGetValue("webhook-id", out var id) ? id : "";\n' +
+            '        var timestamp = headers.TryGetValue("webhook-timestamp", out var ts) ? long.Parse(ts) : 0;\n' +
+            '        var signatures = headers.TryGetValue("webhook-signature", out var sig) ? sig : "";\n\n' +
+            '        var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();\n' +
+            '        if (Math.Abs(now - timestamp) > 300) return false;\n\n' +
+            '        var signed = $"{msgId}.{timestamp}.{payload}";\n' +
+            '        var hex = secret.StartsWith("whsec_") ? secret[6..] : secret;\n' +
+            '        var secretBytes = Convert.FromHexString(hex);\n' +
+            '        using var hmac = new HMACSHA256(secretBytes);\n' +
+            '        var expected = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(signed)));\n\n' +
+            '        foreach (var s in signatures.Split(\' \'))\n' +
+            '        {\n' +
+            '            var v = s.Length > 3 ? s[3..] : "";\n' +
+            '            if (CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(v), Encoding.UTF8.GetBytes(expected)))\n' +
+            '                return true;\n' +
+            '        }\n' +
+            '        return false;\n' +
+            '    }\n' +
+            '}\n',
+          overwrite: false,
+        },
+      ],
+      envVarsNeeded: ENV,
+      nextSteps: NEXT_STEPS,
+      docsUrl: DOCS,
+    },
+    frameworks: {
+      aspnetcore: {
+        channel: 'webhook',
+        language: 'csharp',
+        framework: 'aspnetcore',
+        variant: 'webhook-handler',
+        files: [
+          {
+            path: 'Webhooks/ZyphrWebhookVerifier.cs',
+            purpose: 'Standard Webhooks signature verification helper',
+            contents:
+              'using System.Security.Cryptography;\n' +
+              'using System.Text;\n\n' +
+              'namespace YourApp.Webhooks;\n\n' +
+              'public static class ZyphrWebhookVerifier\n' +
+              '{\n' +
+              '    public static bool Verify(string payload, IHeaderDictionary headers, string secret)\n' +
+              '    {\n' +
+              '        string msgId = headers["webhook-id"].ToString();\n' +
+              '        long timestamp = long.TryParse(headers["webhook-timestamp"], out var t) ? t : 0;\n' +
+              '        string signatures = headers["webhook-signature"].ToString();\n' +
+              '        if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestamp) > 300) return false;\n' +
+              '        var signed = $"{msgId}.{timestamp}.{payload}";\n' +
+              '        var hex = secret.StartsWith("whsec_") ? secret[6..] : secret;\n' +
+              '        using var hmac = new HMACSHA256(Convert.FromHexString(hex));\n' +
+              '        var expected = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(signed)));\n' +
+              '        foreach (var s in signatures.Split(\' \'))\n' +
+              '        {\n' +
+              '            var v = s.Length > 3 ? s[3..] : "";\n' +
+              '            if (CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(v), Encoding.UTF8.GetBytes(expected)))\n' +
+              '                return true;\n' +
+              '        }\n' +
+              '        return false;\n' +
+              '    }\n' +
+              '}\n',
+            overwrite: false,
+          },
+          {
+            path: 'Controllers/ZyphrWebhookController.cs',
+            purpose: 'ASP.NET Core controller that verifies the webhook signature before processing',
+            contents:
+              'using Microsoft.AspNetCore.Mvc;\n' +
+              'using YourApp.Webhooks;\n\n' +
+              '[ApiController]\n' +
+              '[Route("webhooks/zyphr")]\n' +
+              'public class ZyphrWebhookController : ControllerBase\n' +
+              '{\n' +
+              '    [HttpPost]\n' +
+              '    public async Task<IActionResult> Handle()\n' +
+              '    {\n' +
+              '        using var reader = new StreamReader(Request.Body);\n' +
+              '        var payload = await reader.ReadToEndAsync();\n' +
+              '        var secret = Environment.GetEnvironmentVariable("ZYPHR_WEBHOOK_SECRET")!;\n' +
+              '        if (!ZyphrWebhookVerifier.Verify(payload, Request.Headers, secret))\n' +
+              '            return Unauthorized("invalid signature");\n' +
+              '        Console.WriteLine($"zyphr event {payload[..Math.Min(80, payload.Length)]}");\n' +
+              '        return NoContent();\n' +
+              '    }\n' +
+              '}\n',
+            overwrite: false,
+          },
+        ],
+        envVarsNeeded: ENV,
+        nextSteps: NEXT_STEPS,
+        docsUrl: DOCS,
+      },
+    },
+  },
+};