// webhooks

Retrace Webhooks

Deliver Retrace events to your HTTPS endpoint for evaluation results, trace failures, guardrail triggers, and workflow automation.

Start freeRead the docs →

HTTPS only

Webhook destinations must use HTTPS. Retrace rejects private and internal network targets before delivery.

Verify before processing

Validate the delivery signature against the raw request body before parsing or acting on an event.

Handle retries safely

Use the delivery identifier as an idempotency key because transient failures can cause an event to be delivered again.

Return quickly

Acknowledge valid events with a 2xx response, then move expensive processing to your own background worker.

handler.ts
export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("x-retrace-signature");
  verifyRetraceSignature(rawBody, signature, process.env.RETRACE_WEBHOOK_SECRET);
  await enqueue(JSON.parse(rawBody));
  return new Response(null, { status: 204 });
}

Preserve the raw request body for signature verification.

Webhook contract

More for developers

// python sdkPython SDKRecord Python agents with one decorator// typescript sdkTypeScript SDKTrace TS/JS agents with a function wrapper// api referenceAPI ReferenceThe full REST + streaming API// authenticationAuthenticationAuthenticate Retrace API, SDK, CLI, and MCP calls// mcp serverMCP ServerCall Retrace from agents over Streamable HTTP// command lineCLIScript Retrace workflows from a terminal or CI