API REST v1, de la primera llamada a producción.

Crea una credencial de servicio en Agentes → REST v1 con vigencia de 30, 90, 180 o hasta 365 días. El secreto f4_live_ se muestra una sola vez: guárdalo en un gestor de secretos, rótalo antes de vencer y nunca lo incluyas en código del navegador.

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"
  }
}

Cada clave pertenece a un workspace, puede limitarse a un proyecto, tiene scopes explícitos y una fecha de expiración. El servidor conserva únicamente el hash. Revocar la clave o retirar a su creador corta el acceso.

Scopes disponibles

Todas las respuestas llevan X-Request-Id y Cache-Control: no-store. Envía un X-Request-Id de 8–100 caracteres seguros para correlacionar tus logs; si no, Feedback4 genera uno.

{
  "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" }
    ]
  }
}

Todos los paths siguientes se agregan a https://feedback4.dev/api/v1. Los IDs son UUID y los recursos fuera del workspace o proyecto se responden como 404 para no revelar su existencia.

Cada agencia puede registrar uno o más endpoints por workspace o por proyecto. Feedback4 persiste primero el evento, crea una entrega independiente por suscripción y hace el POST en segundo plano; la captura del usuario nunca espera al receptor. agent_mode comunica la política a la automatización externa: off entrega policy=do_not_execute, propose exige propuesta y autorización, y auto permite al agente externo implementar antes de pedir aprobación. Feedback4 no ejecuta el agente.

1. Registrar 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"
  }'

La respuesta 201 incluye signing_secret una sola vez. Guárdalo como secreto de servidor. Usa authentication=hmac_sha256_and_shared_secret y shared_secret sólo para receptores heredados —como la primera integración de Aviso.Gratis— que además requieren x-feedback4-secret. Las URLs deben ser HTTPS públicas; se rechazan credenciales embebidas, fragments, localhost, redes privadas, link-local y metadata.

2. Validar la entrega

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. Payload v1

{
  "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 confirma cualquier 2xx, respeta Retry-After en 429, deshabilita el endpoint ante 410 y reintenta timeouts, redirects, otros 4xx y 5xx con backoff exponencial de hasta 6 horas. El timeout por intento es 10 segundos, no se siguen redirects y tras 16 intentos la entrega pasa a dead letter. Consulta GET /webhook-endpoints/{endpoint_id}/deliveries y usa POST /webhook-deliveries/{delivery_id}/retry después de corregir el receptor.

v1 mantiene compatibilidad hacia atrás. Los campos nuevos pueden aparecer sin romper consumidores; ignora propiedades desconocidas en respuestas. Los cambios incompatibles se publicarán en una nueva versión y se anunciarán antes de retirar v1.