Feedback API

The <script> widget is the fastest way to collect feedback, but you don't have to use it. If you're building your own submission UI — a settings page, a support modal, a CLI — post directly to the ingestion endpoint. It's the same API the widget calls.

Submit feedback

A single POST. Your widget key authenticates the request — it's a public embed key, safe to ship in client code. It routes feedback to your project; it is not your worker token.

POST https://fdbck.app/api/v1/feedback
Content-Type: application/json
X-Widget-Key: wk_your_key_here
X-Idempotency-Key: 8f3b…   (optional)

Headers

X-Widget-Key is required. Send Content-Type: application/json too — the body is parsed as JSON regardless, but it's the correct content type. X-Idempotency-Key is optional: pass any UUID and a repeat with the same key within 24 hours returns the original submission instead of creating a duplicate. Mint one key per composed message and reuse it across retries — a fresh key per attempt defeats the point.

Body fields

Only message is required. Everything else is optional context that helps triage.

Example

curl https://fdbck.app/api/v1/feedback \
  -H "Content-Type: application/json" \
  -H "X-Widget-Key: wk_your_key_here" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "message": "The export button on the reports page does nothing.",
    "type": "bug",
    "url": "https://app.example.com/reports",
    "user_id": "usr_1042",
    "email": "sam@example.com",
    "metadata": { "plan": "pro", "build": "1.4.2" }
  }'

Response

A fresh submission returns 201 with the item id and a status link you can show the submitter so they can follow their feedback.

{
  "id": "b1f0…",
  "statusUrl": "https://fdbck.app/feedback/status/…"
}

When an X-Idempotency-Key matches a submission from the last 24 hours, the endpoint returns 200 with the existing id (and no statusUrl) — the earlier item stands, nothing new is created.

Errors

Every error is JSON with a machine-readable error code and a hint describing what to do.

Fetch widget config

If you're rendering your own submission UI, you can pull the owner's presentation choices — the confirmation copy, footer links, accent, redirect — from the same config the embedded widget reads. It's keyed by the public widget key, read-only, and cached at the edge for about 60 seconds. Rate limit is 60 requests per minute per key.

GET https://fdbck.app/api/v1/widget/config?key=wk_your_key_here

Owners set all of this in Settings → Widget messaging — no code change on your side; re-fetch to pick up their edits.

Error webhook

Beyond human feedback, you can pipe runtime errors straight into the same inbox — from an error tracker, a logging pipeline, or your own catch block. Unlike the public widget key, this endpoint is signed with your project's webhook secret (Settings → General), so only your servers can post errors.

BODY='{"error":"TypeError: cannot read x of undefined","file":"checkout.ts"}'
TS=$(($(date +%s) * 1000))                 # epoch MILLISECONDS

# Sign "{timestamp}.{body}" (or just the body if you omit X-Timestamp).
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$FDBCK_WEBHOOK_SECRET" | awk '{print $2}')

curl -X POST https://fdbck.app/api/v1/webhooks/error \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: your-project-id" \
  -H "X-Webhook-Secret: $SIG" \
  -H "X-Timestamp: $TS" \
  -d "$BODY"

Compute an HMAC-SHA256 with your webhook secret and send the hex digest as X-Webhook-Secret. If you include X-Timestamp (epoch milliseconds), sign {timestamp}.{body} and it enables replay protection (±5-minute window); otherwise sign the raw body alone. Rate limit: 60 requests per minute per project.

PII & safety