Skip to content

integrations.md

Latest commit

 

History

History
168 lines (125 loc) · 3.36 KB

integrations.md

File metadata and controls

168 lines (125 loc) · 3.36 KB

Integrations and APIs

Table of contents

  1. Internal APIs
  2. Webhook model
  3. Webhook payload
  4. Authentication
  5. Integration guidance

Internal APIs

FORMNA includes internal authenticated JSON endpoints for browser-driven interactions.

Questions

POST   /api/questions
GET    /api/questions/{uid}
POST   /api/questions/{uid}
DELETE /api/questions/{uid}
POST   /api/questions/reorder

Drafts

POST   /api/drafts/{form_uuid}
GET    /api/drafts/{form_uuid}
DELETE /api/drafts/{form_uuid}

Files

POST   /api/files/upload
DELETE /api/files/{id}

Notifications

GET    /api/notifications
POST   /api/notifications/{id}/read
POST   /api/notifications/read-all
POST   /api/notifications/clear-all

Clarifications

POST   /api/clarifications/{uuid}/resolve
POST   /api/clarifications/{uuid}/reject
POST   /api/clarifications/{uuid}/cancel

Admin-specific APIs

POST   /api/admin/ai/summarize
GET    /api/admin/ai/summary/{type}/{uuid}
GET    /api/admin/forms/{uuid}/admins
POST   /api/admin/forms/{uuid}/admins
PATCH  /api/admin/forms/{uuid}/admins/{id}
DELETE /api/admin/forms/{uuid}/admins/{id}
GET    /api/admin/users/search

Webhook model

Webhooks are configured per form and triggered when a form submission event occurs.

Current documented behavior includes:

  • one webhook per form
  • Bearer token authentication
  • retry attempts with backoff
  • delivery logs and manual testing support

Webhook payload

{
  "event": "form.submitted",
  "timestamp": "2026-06-18T15:00:00Z",
  "form": {
    "id": "form-uuid",
    "name": "Application Form",
    "version": 2
  },
  "submission": {
    "id": "submission-uuid",
    "submitted_at": "2026-06-18T15:00:00Z",
    "user": {
      "id": 123,
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "answers": {
      "question_uid": "answer value"
    },
    "score": 85
  }
}

File-answer payloads may include file IDs, filenames, and authenticated download URLs.

Authentication

Webhooks use Bearer token authentication. Each webhook includes a configurable bearer token that is sent in the Authorization header.

POST /your-endpoint HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer your_webhook_bearer_token_here
User-Agent: FORMNA-Webhook/1.0

Your webhook endpoint should validate the Bearer token:

$authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
$expectedToken = 'your_webhook_bearer_token_here';

if ($authHeader !== "Bearer {$expectedToken}") {
    http_response_code(401);
    exit('Unauthorized');
}

$payload = file_get_contents('php://input');
// Process webhook...

Integration guidance

For outgoing integrations

  • keep destination endpoints fast
  • return 2xx status codes on success
  • log payloads on the receiving side
  • verify Bearer tokens before processing

For AI integration

The platform can optionally use OpenAI-backed summaries for reviewers. Documented settings include:

  • API key
  • model selection
  • token limits
  • feature enablement
  • connection testing

For email integration

All email delivery is SMTP-based and queue-driven. Test template rendering and delivery before production rollout.