Skip to main content
The easiest way to test your webhook integration is using the built-in tunnel in the AgentMark dev server. This creates a public URL that the AgentMark platform can reach, without requiring you to deploy anything.

​
Local Testing with Tunnel

1

Start the Dev Server with Tunnel

Run the dev server with the --tunnel flag:
agentmark dev --tunnel
On the first run, this downloads the Cloudflare tunnel binary (~30MB). After setup, you’ll see output like:
Public Webhook:
  URL:    https://random-words.trycloudflare.com
  Secret: a1b2c3d4e5f6...
  Valid:  30 days
2

Add the Webhook URL in the Platform

  1. Open your app in the AgentMark dashboard
  2. Navigate to Settings
  3. Paste the tunnel URL into the Webhook URL field
  4. Paste the secret into the Webhook Secret field
  5. Save
3

Run a Prompt from the Platform

  1. Open a prompt in the platform editor
  2. Click Run
  3. The platform sends the prompt event to your tunnel URL
  4. Your local dev server executes the prompt using your adapter and models
  5. The result streams back to the platform
You can watch the request in your terminal and inspect traces in the local dashboard at http://localhost:3000.
The tunnel URL and secret are stored in .agentmark/dev-config.json and persist for 30 days. You don’t need to reconfigure the platform each time you restart the dev server.

​
How It Works

When you run agentmark dev --tunnel, three services start:
ServicePortPurpose
API server9418Serves prompts, collects traces
Webhook server9417Receives and executes prompt/dataset events
Dashboard3000View traces, sessions, and requests
The tunnel exposes your local webhook server (port 9417) to a public Cloudflare URL. The platform sends events to this URL, and your webhook server processes them using the handler defined in your dev-entry.ts. When the tunnel is active, all incoming requests are verified using the x-agentmark-signature-256 header and your webhook secret. In local-only mode (without --tunnel), signature verification is skipped for convenience.

​
Webhook Handlers

Each adapter provides a webhook handler via its /runner export. This is configured automatically in your dev-entry.ts:
dev-entry.ts
import { createWebhookServer } from '@agentmark-ai/cli/runner-server';
import { VercelAdapterWebhookHandler } from '@agentmark-ai/ai-sdk-v5-adapter/runner';

const { client } = await import('./agentmark.client.js');
const handler = new VercelAdapterWebhookHandler(client);

await createWebhookServer({
  port: 9417,
  handler,
  apiServerUrl: 'http://localhost:9418',
  templatesDirectory: './agentmark',
});
The dev-entry.ts file is generated by npm create agentmark@latest and is version-controlled. You can customize it to add additional setup logic.

​
Supported Events

The webhook server handles these event types from the platform:
EventDescription
prompt-runExecute a single prompt from the platform editor
dataset-runRun a prompt against a dataset for experiments
Alert events are sent directly to your production webhook endpoint and are not handled by the local dev server.

​
Troubleshooting

IssueSolution
Tunnel fails to startCheck internet connection. Set AGENTMARK_SKIP_CLOUDFLARED_DOWNLOAD=true to skip if behind a proxy and install cloudflared manually
Platform can’t reach webhookEnsure the tunnel URL in Settings matches the one printed in your terminal
Signature verification failsThe secret in the platform must match the one from agentmark dev --tunnel output
Prompts not foundMake sure the dev server is running and your agentmark/ directory contains the prompt files

​
Production Webhooks

For production deployments, you’ll need a publicly accessible webhook endpoint. See the full webhook documentation:

Webhook Setup

Deploy a production webhook endpoint

Webhook Helpers

In-depth webhook helper reference

​
Have Questions?

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