This guide will help you set up your webhook endpoint to handle AgentMark events using the WebhookHelper.

If you are not using the Vercel AI SDK or prefer to handle events manually without the WebhookHelper, please see our detailed event documentation to build your own handler from scratch.

​
Prerequisites

  • Node.js 18+ environment
  • Next.js application (or similar framework)
  • AgentMark API credentials

​
1. Get Your Credentials

  1. Navigate to the Settings page in your AgentMark dashboard
  2. Under “Webhook Settings”, you’ll find:
    • Webhook URL input field
    • Webhook secret for signature verification
    • API key and App ID

Keep your webhook secret and API credentials secure! These are used to verify requests and authenticate with AgentMark.

​
2. Install Dependencies

Install the necessary packages to get started:

npm install ai @ai-sdk/openai @agentmark/agentmark-core @agentmark/sdk @agentmark/shared-utils @agentmark/vercel-ai-v4-adapter @agentmark/vercel-ai-v4-webhook-helper

​
3. Set up your Endpoint

First, set up your environment variables:

AGENTMARK_API_KEY=your_api_key
AGENTMARK_APP_ID=your_app_id
AGENTMARK_WEBHOOK_SECRET=your_webhook_secret

Then, create your webhook endpoint. The example below uses Next.js App Router.

import { NextRequest, NextResponse } from "next/server";
import { AgentMarkSDK } from "@agentmark/sdk";
import { verifySignature } from "@agentmark/shared-utils";
import {
  createAgentMarkClient,
  VercelAIModelRegistry,
} from "@agentmark/vercel-ai-v4-adapter";
import { openai } from "@ai-sdk/openai";
import { WebhookHelper } from "@agentmark/vercel-ai-v4-webhook-helper";

export const dynamic = "force-dynamic";

// Initialize AgentMark SDK
const sdk = new AgentMarkSDK({
  apiKey: process.env.AGENTMARK_API_KEY,
  appId: process.env.AGENTMARK_APP_ID,
});

// Required for tracing dataset runs
sdk.initTracing({ disableBatch: true });

// Set up model registry with all supported models
const modelRegistry = new VercelAIModelRegistry();

// Register models
modelRegistry.registerModels(
  ["gpt-4o", "gpt-4-turbo", "gpt-3.5-turbo"],
  (name: string) => openai(name)
);

// Create AgentMark client
const agentmark = createAgentMarkClient({
  modelRegistry,
  loader: sdk.getFileLoader(),
});

// Create Webhook Handler
export async function POST(request: NextRequest) {
  const payload = await request.json();
  const headers = request.headers;
  const xAgentmarkSign = headers.get("x-agentmark-signature-256");

  try {
    // Verify signature
    if (!xAgentmarkSign) {
      throw new Error("Missing x-agentmark-signature-256 header");
    }

    if (!(await verifySignature(
      process.env.AGENTMARK_WEBHOOK_SECRET!,
      xAgentmarkSign,
      JSON.stringify(payload)
    ))) {
      throw new Error("Invalid signature");
    }

    const event = payload.event;
    const webhookHelper = new WebhookHelper(agentmark);

    if (event.type === "prompt-run") {
      const response = await webhookHelper.runPrompt(event.data);
      if (response.type === "stream") {
        return new Response(response.stream, {
          headers: { ...response.streamHeader },
        });
      }
      return NextResponse.json(response);
    }

    if (event.type === "dataset-run") {
      const response = await webhookHelper.runDataset(event.data);
      return new Response(response.stream, {
        headers: {
          ...response.streamHeaders,
        },
      });
    }
    
    if (event.type === "alert") {
        // Alerts are not handled by the helper, process manually
        console.log("Alert received:", event.data);
        return NextResponse.json({ message: "alert processed" });
    }

    throw new Error(`Unknown event type: ${event.type}`);
  } catch (error) {
    console.error("Webhook error:", error);
    return NextResponse.json(
      { message: "Internal server error" },
      { status: 500 }
    );
  }
}

​
4. Security Best Practices

  1. Signature Verification

    • Always verify the x-agentmark-signature-256 header
    • Use the webhook secret to validate requests
    • Reject requests with invalid signatures

  2. Error Handling

    • Implement proper error handling
    • Return appropriate HTTP status codes
    • Log errors for debugging

  3. Environment Security

    • Use environment variables for sensitive data
    • Keep your webhook secret secure
    • Use HTTPS for your endpoint

​
5. Testing Your Setup

  1. Deploy your webhook endpoint
  2. Add your webhook URL in AgentMark settings
  3. Create a test prompt
  4. Click “Run” to send a test request
  5. Verify the response in your logs

Make sure your webhook endpoint is publicly accessible and can handle POST requests.

​
Next Steps

Have Questions?

We’re here to help! Choose the best way to reach us: