Webhooks

Two delivery patterns are supported:

Per-request — include webhook_url on a single generation call. One-shot; fires once for that task.
Subscriptions — call POST /webhooks once per org; fires for every matching event thereafter.

Subscriptions are the right default for production. Per-request is handy for ad-hoc scripts or testing.

Events

Currently we fire two events:

run.completed — a task transitioned to status=completed
run.failed — a task transitioned to status=failed

Subscriptions are opt-in per event via the events field when subscribing (see below). Subscribe only to the events you actually handle.

Subscribing

POST /api/v1/webhooks
X-API-Key: $OVERTEN_API_KEY
Content-Type: application/json

{
  "url": "https://myapp.example.com/webhooks/overten",
  "events": ["run.completed", "run.failed"],
  "description": "Production production pipeline"
}

Response:

{
  "webhook_id": "whk_...",
  "url": "https://myapp.example.com/webhooks/overten",
  "events": ["run.completed", "run.failed"],
  "description": "Production pipeline",
  "active": true,
  "secret": "whsec_...",
  "created_at": "..."
}

The secret is shown only once. Save it — you need it to verify signatures. Losing it means deleting the subscription and creating a new one.

Per-request webhooks

If you just want a single callback for one task:

POST /excel/generate
{
  "prompt": "...",
  "async": true,
  "webhook_url": "https://myapp.example.com/webhooks/overten"
}

This fires against your org’s primary webhook secret (from GET /verify), not a per-subscription one. Same signature scheme.

Payload shape

POST https://myapp.example.com/webhooks/overten
Content-Type: application/json
X-Overten-Signature: sha256=<hex_hmac>
X-Overten-Timestamp: 1713312345
X-Overten-Event: run.completed
User-Agent: Overten-Webhook/1.0

{
  "event": "run.completed",
  "run_id": "run_01HXYZ",
  "task_id": "task_01HXYZ",
  "agent_name": "excel_agent_api",
  "format": "excel",
  "status": "completed",
  "download_url": "https://...",
  "edit_url": "https://...",
  "summary": "Created a 12-row sales report...",
  "occurred_at_ms": 1713312345678
}

On run.failed the shape is:

{
  "event": "run.failed",
  "run_id": "run_01HXYZ",
  "task_id": "task_01HXYZ",
  "agent_name": "excel_agent_api",
  "format": "excel",
  "error": {
    "code": "internal_error",
    "message": "..."
  },
  "occurred_at_ms": 1713312345678
}

Verifying signatures

The signature is computed as:

signed_payload = f"{timestamp}.{raw_body}"
signature      = hmac.new(secret, signed_payload, sha256).hexdigest()

Where timestamp is the X-Overten-Timestamp header value and raw_body is the exact bytes of the POST body (not re-serialized JSON).

import hmac, hashlib, time
from fastapi import Request, HTTPException

SECRET = "whsec_..."

async def verify(request: Request):
    body = await request.body()
    sig_header = request.headers.get("X-Overten-Signature", "")
    ts = request.headers.get("X-Overten-Timestamp", "")
    if not sig_header.startswith("sha256="):
        raise HTTPException(400, "missing signature")
    expected_sig = sig_header.removeprefix("sha256=")

    # Replay protection: reject > 5 min old
    if abs(time.time() - int(ts)) > 300:
        raise HTTPException(400, "timestamp too old")

    signed_payload = f"{ts}.{body.decode()}".encode()
    computed = hmac.new(SECRET.encode(), signed_payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(computed, expected_sig):
        raise HTTPException(400, "bad signature")

import crypto from "node:crypto";

const SECRET = process.env.OVERTEN_WEBHOOK_SECRET;

export function verify(req) {
  const sigHeader = req.headers["x-overten-signature"] || "";
  const ts = req.headers["x-overten-timestamp"] || "";

  if (!sigHeader.startsWith("sha256=")) throw new Error("missing signature");
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) throw new Error("stale");

  const body = req.rawBody;  // original bytes, not JSON.stringify(req.body)
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${ts}.${body}`)
    .digest("hex");

  const given = sigHeader.replace(/^sha256=/, "");
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given))) {
    throw new Error("bad signature");
  }
}

package webhook

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "net/http"
    "strconv"
    "strings"
    "time"
)

const secret = "whsec_..."

func Verify(r *http.Request, body []byte) error {
    sig := strings.TrimPrefix(r.Header.Get("X-Overten-Signature"), "sha256=")
    ts := r.Header.Get("X-Overten-Timestamp")

    n, _ := strconv.ParseInt(ts, 10, 64)
    if abs64(time.Now().Unix()-n) > 300 {
        return fmt.Errorf("stale timestamp")
    }

    signedPayload := ts + "." + string(body)
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(signedPayload))
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(sig), []byte(expected)) {
        return fmt.Errorf("bad signature")
    }
    return nil
}

Retry policy

Non-2xx responses trigger retries with exponential backoff:

1s → 4s → 16s → 64s → 256s → 1024s → 4096s

Seven attempts total, ~1.5h total window. After the last attempt we give up; the task itself is still completed (or failed) on our side — only the notification was lost. Your application should be idempotent and not depend on the webhook firing exactly once. 4xx responses are not retried — if your endpoint returns 400/401/404, we assume your service is saying “don’t try again.”

Best practices

Respond fast, process async

Return 200 immediately and enqueue the work internally. We time out at 15 seconds per attempt; if your handler runs synchronously longer than that we’ll treat it as a failure.

Be idempotent on run_id + event

Retries and edge cases can cause duplicate deliveries. Key your processing on (run_id, event) and skip if already handled.

Verify signatures

Webhook URLs are attacker-reachable. Signatures prove it came from us. Never trust the payload without verifying.

Store the secret like a database password

If it leaks, rotate by deleting the subscription and recreating it — the new subscription will issue a fresh secret. Old signatures will stop validating immediately.

Debugging

The dashboard’s Webhooks → Delivery log shows every attempt for the last 30 days with:

HTTP status received
Response body (truncated to 1KB)
Latency per attempt
Retry schedule remaining

If deliveries are failing, check there first before reaching out to support.

Get started

Core concepts

Project intelligence

Format guides

Reference

Events

Subscribing

Per-request webhooks

Payload shape

Verifying signatures

Retry policy

Best practices

Debugging

​Events

​Subscribing

​Per-request webhooks

​Payload shape

​Verifying signatures

​Retry policy

​Best practices

​Debugging

Events

Subscribing

Per-request webhooks

Payload shape

Verifying signatures

Retry policy

Best practices

Debugging