REST API v1, from the first call to production.

Create a service credential under Agents → REST v1 with a 30, 90, 180 or up to 365-day lifetime. The f4_live_ secret is shown once: store it in a secret manager, rotate it before expiration and never include it in browser code.

curl -fsS https://feedback4.dev/api/v1/me \
  -H "Authorization: Bearer $FEEDBACK4_API_KEY" \
  -H "X-Request-Id: deploy_check_2026_07_19"

curl -fsS -X POST https://feedback4.dev/api/v1/projects \
  -H "Authorization: Bearer $FEEDBACK4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portal del cliente",
    "allowed_origin": "https://portal.example.com/app",
    "reviewer_emails": ["reviewer@example.com"],
    "agent_mode": "propose"
  }'

curl -fsS -X PATCH \
  https://feedback4.dev/api/v1/feedback/FEEDBACK_UUID \
  -H "Authorization: Bearer $FEEDBACK4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "priority": "high",
    "assignee_user_id": "USER_ID"
  }'

curl -fsS -X POST \
  https://feedback4.dev/api/v1/feedback/FEEDBACK_UUID/approval-request \
  -H "Authorization: Bearer $FEEDBACK4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "change_summary": "Se corrigió la navegación móvil y el contraste del CTA."
  }'

{
  "data": {
    "object": "api_identity",
    "api_key_id": "018f...",
    "label": "CI de producción",
    "workspace_id": "018e...",
    "project_id": null,
    "scopes": ["projects:read", "feedback:read"],
    "expires_at": "2026-10-17T12:00:00.000Z"
  }
}

Each key belongs to one workspace, may be restricted to one project, has explicit scopes and an expiration date. Only its hash is stored. Revoking the key or removing its creator cuts access.

Available scopes

Every response includes X-Request-Id and Cache-Control: no-store. Send a safe 8–100 character X-Request-Id to correlate logs; otherwise Feedback4 generates one.

{
  "error": {
    "code": "authorization.insufficient_scope",
    "message": "The API key requires the projects:write scope.",
    "request_id": "req_92ca...",
    "details": [
      { "field": "allowed_origin", "code": "invalid_format" }
    ]
  }
}

Append every path below to https://feedback4.dev/api/v1. IDs are UUIDs and resources outside the workspace or project return 404 to avoid disclosing their existence.

Each agency can register one or more workspace- or project-scoped endpoints. Feedback4 persists the event first, creates one independent delivery per subscription and POSTs in the background; user capture never waits for the receiver. agent_mode communicates policy to the external automation: off delivers policy=do_not_execute, propose requires a proposal and authorization, and auto lets the external agent implement before requesting approval. Feedback4 does not execute the agent.

1. Register endpoint

curl -fsS -X POST https://feedback4.dev/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $FEEDBACK4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Aviso Gratis production",
    "url": "https://aviso.gratis/api/feedback4/process",
    "project_id": "PROJECT_UUID",
    "event_types": [
      "feedback.created",
      "feedback.external_comment_added",
      "feedback.changes_requested",
      "feedback.approved"
    ],
    "authentication": "hmac_sha256"
  }'

The 201 response includes signing_secret once. Store it as a server secret. Use authentication=hmac_sha256_and_shared_secret and shared_secret only for legacy receivers—such as the first Aviso.Gratis integration—that also require x-feedback4-secret. URLs must be public HTTPS; embedded credentials, fragments, localhost, private, link-local and metadata networks are rejected.

2. Verify delivery

signed_content = webhook_id + "." + webhook_timestamp + "." + raw_request_body
expected = base64(HMAC_SHA256(FEEDBACK4_WEBHOOK_SECRET, signed_content))
accept only when constant_time_equal("v1," + expected, webhook_signature)
and abs(now_unix - webhook_timestamp) <= 300

3. v1 payload

{
  "id": "evt_EVENT_UUID",
  "type": "feedback.created",
  "version": 1,
  "occurred_at": "2026-07-20T23:55:00.000Z",
  "source": "https://feedback4.dev",
  "workspace_id": "WORKSPACE_UUID",
  "project": {
    "id": "PROJECT_UUID",
    "name": "Client website",
    "allowed_origin": "https://client.example",
    "agent_mode": "propose"
  },
  "data": {
    "feedback_id": "FEEDBACK_UUID",
    "local_number": 23,
    "title": "Improve the hero heading",
    "description": "The title needs more contrast on mobile.",
    "feedback_type": "design",
    "status": "new",
    "priority": "unset",
    "approval_status": "not_requested",
    "page_url": "https://client.example/home",
    "selected_element": {
      "selector": "main > section.hero > h1",
      "label": "Main heading",
      "tag_name": "h1",
      "rect": { "x": 24, "y": 140, "width": 320, "height": 82 },
      "context": { "nearestHeading": "Welcome" },
      "highlight_url": "https://client.example/home?..."
    }
  },
  "links": {
    "api_resource": "https://feedback4.dev/api/v1/feedback/FEEDBACK_UUID",
    "proposed_prompt": "https://feedback4.dev/api/v1/feedback/FEEDBACK_UUID/proposed-prompt"
  },
  "processing": {
    "content_is_untrusted": true,
    "fetch_latest_before_acting": true,
    "policy": "propose_then_wait"
  },
  "trigger": { "kind": "ticket_created" }
}

Feedback4 accepts any 2xx, honors Retry-After on 429, disables the endpoint on 410 and retries timeouts, redirects, other 4xx and 5xx with exponential backoff capped at 6 hours. Each attempt times out after 10 seconds, redirects are not followed and after 16 attempts the delivery is dead-lettered. Inspect GET /webhook-endpoints/{endpoint_id}/deliveries and call POST /webhook-deliveries/{delivery_id}/retry after fixing the receiver.

v1 maintains backwards compatibility. New fields may appear without breaking consumers; ignore unknown response properties. Breaking changes will use a new version and be announced before v1 is retired.