AgentMark’s webhook allows you to receive events from AgentMark and respond to them. AgentMark supports helpers that automatically handle tracing, formatting, and more.

AgentMark handles the following events:

  • Prompt Runs - When a prompt is run in the AgentMark platform
  • Dataset Runs - When a dataset is run in the AgentMark platform
  • Alerts - When an alert is triggered or resolved in the AgentMark platform

​
Webhook Endpoint

import { NextRequest, NextResponse } from "next/server";
import { AgentMarkSDK } from "@agentmark/sdk";
import { verifySignature } from "@agentmark/shared-utils";
import { agentmarkClient, agentmarkCloudSDK } from "./agentmark";
// Use the appropriate helper for your chosen framework
import { WebhookHelper } from "@agentmark/vercel-ai-v4-webhook-helper";

// 2. Create the webhook endpoint
export async function POST(request: NextRequest) {
  const payload = await request.json();
  const headers = request.headers;
  const xAgentmarkSign = headers.get("x-agentmark-signature-256");
  agentmarkCloudSDK.initTracing({ disableBatch: true });

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

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

    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 these 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 }
    );
  }
}

For more details on helpers, event types, and security best practices, please refer to the main Webhook documentation. If you’re not using using a custom framework, see our event-specific guides.

​
Security Best Practices

  • Always verify the x-agentmark-signature-256 header
  • Use environment variables for sensitive data
  • Implement proper error handling
  • Return appropriate HTTP status codes
  • Use HTTPS for your endpoint

​
Common Issues

  • Signature Verification: Ensure your webhook verifies the x-agentmark-signature-256 header
  • Error Handling: Implement proper error handling and return appropriate status codes
  • Response Format: Follow the expected response format for each event type