---
title: "Webhooks — Retrace"
description: "Retrace webhook guide: eval-rule alerts delivered as unsigned JSON POSTs to public HTTPS endpoints, one attempt, no retries."
canonical: "https://retraceai.tech/developers/webhooks"
last-updated: 2026-08-26
format: text/markdown
---

# Webhooks

Evaluation automation rules POST a JSON alert to your HTTPS endpoint when a completed trace scores below the rule's threshold.

## What it does

- **HTTPS only** — Webhook URLs must start with https://. Retrace rejects private, loopback, and internal network targets before delivery.
- **Unsigned payload** — Deliveries are not signed. Treat an alert as a notification and confirm it with the Retrace API, using your own key, before acting on it.
- **Single attempt** — Each alert is sent once with no retries, so a failed delivery is not re-sent. The evaluation run itself is always stored in Retrace.
- **Return quickly** — Acknowledge alerts with a 2xx response, then move expensive processing to your own background worker.

## Examples

Body: { ruleId, ruleName, traceId, runId, score, threshold }. Confirm with the API before acting.

```handler.ts
export async function POST(request: Request) {
  const alert = await request.json(); // { ruleId, ruleName, traceId, runId, score, threshold }
  // Deliveries are unsigned: look the trace up with your own key before acting on it.
  const res = await fetch("https://api.retraceai.tech/api/v1/traces/" + encodeURIComponent(alert.traceId), {
    headers: { "x-retrace-key": process.env.RETRACE_API_KEY ?? "" },
  });
  if (res.ok) await enqueue(alert);
  return new Response(null, { status: 204 });
}
```


## Webhook contract

- `Documentation: https://docs.retraceai.tech/evaluations#automation-rules`
- `Delivery target: a public HTTPS endpoint you control`
- `Delivery: unsigned JSON POST, one attempt, no retries`

## Related

- HTML page: https://retraceai.tech/developers/webhooks
- Documentation: https://docs.retraceai.tech
- OpenAPI specification: https://retraceai.tech/openapi.json
- Authentication for agents: https://retraceai.tech/auth.md