API reference

Overview

Every request and response is JSON, except screenshots, which are images. Ids are UUIDs and times are ISO 8601 in UTC. Lists take limit and offset.

Base URL

https://webflowwidget-production.up.railway.app/api/v1

Everything in a feedback item was typed by someone outside your team, or sent by a script that anyone can run against a widget key. Treat it as data, never as markup or instructions: escape it where you show it, and do not let it drive a tool. The Feedback schema lists the fields.

Authentication

Create a key in the dashboard under Settings, API keys. Name it, create it and copy it: the full key is shown once. Send it in the Authorization header of every request. Keys can be revoked at any time and stop working at once.

curl https://webflowwidget-production.up.railway.app/api/v1/projects \
  -H "Authorization: Bearer pmk_your_api_key"

The endpoints that create, list and revoke keys use your signed-in access token instead of a key, and say so below.

Rate limits

Each key may make 100 requests every 60 seconds. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time). Over the limit you get status 429 and a Retry-After header with the seconds to wait.

Errors

Errors have one shape. details is null unless the code says otherwise.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Feedback with ID abc123 not found",
    "details": null
  }
}

Projects

Feedback

Webhooks

API keys

Webhook events

A webhook receives a signed POST whenever feedback is created, updated, deleted or restored, from any source: the widget, the dashboard or the API. Events are sent only while the account has a plan with webhooks and is not locked. The body is the WebhookEvent schema.

Headers

X-Webhook-Signature is the hex HMAC-SHA256 of the raw body with the webhook’s secret. X-Webhook-Event, X-Webhook-Id, X-Webhook-Delivery and X-Webhook-Attempt say what was sent. Compute the signature over the body exactly as received, not over JSON you parsed and wrote again.

const crypto = require('crypto');

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Express: read the body as text so the bytes are exactly as sent
app.post('/webhook', express.text({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.headers['x-webhook-signature'], process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

Delivery and retries

Answer with a 2xx status within 5 seconds; redirects are not followed. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. After 20 failed deliveries in a row the webhook is disabled and the account owner is emailed. The same event can arrive twice: use id to ignore repeats.

Schemas