Form Events

Form events are triggered when forms are submitted in the Tracktile platform.

TypeScript Interfaces

Copy these interfaces to type your webhook handlers:

/** Base event properties included in all webhook events */
interface BaseEvent {
  /** Unique event identifier (UUID) */
  id: string;
  /** Event type */
  kind: string;
  /** ISO 8601 timestamp */
  time: string;
  /** Transaction identifier for grouping related events */
  transactionId: string;
}

/** Form submission action types */
type FormSubmissionAction = "submit" | "approve" | "reject" | "cancel";

/** Form submission object */
interface FormSubmission {
  /** Submission UUID */
  id: string;
  /** Form template UUID */
  formId: string;
  /** Form template name */
  formName: string;
  /** User who submitted */
  submittedBy: string;
  /** Submission timestamp */
  submittedAt: string;
  /** Form field values */
  values: Record<string, unknown>;
}

---

form.submitted

Triggered when a form is submitted.

Example

{
  "id": "evt_abc123",
  "kind": "form.submitted",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "formSubmission": {
    "id": "sub_456",
    "formId": "form_789",
    "formName": "Quality Inspection",
    "submittedBy": "user_123",
    "submittedAt": "2024-01-15T10:30:00Z",
    "values": {
      "temperature": 4.5,
      "humidity": 65,
      "passed": true,
      "notes": "All checks passed"
    }
  },
  "action": "submit",
  "requiresApproval": false
}

TypeScript

interface FormSubmittedEvent extends BaseEvent {
  kind: "form.submitted";
  /** The form submission data */
  formSubmission: FormSubmission;
  /** Action that triggered this event */
  action: FormSubmissionAction;
  /** Whether the submission requires approval */
  requiresApproval: boolean;
}

Form Submission Actions

Action	Description
submit	Initial form submission
approve	Submission approved (for forms requiring approval)
reject	Submission rejected
cancel	Submission cancelled

---

All Form Event Types

Union type for handling any form event:

type FormEvent = FormSubmittedEvent;

// Type guard for form events
function isFormEvent(event: BaseEvent): event is FormEvent {
  return event.kind.startsWith("form.");
}

// Example webhook handler
async function handleFormWebhook(event: FormEvent) {
  switch (event.kind) {
    case "form.submitted":
      const { formSubmission, action, requiresApproval } = event;
      console.log(
        `Form ${formSubmission.formName} ${action}ed by ${formSubmission.submittedBy}`
      );

      if (requiresApproval) {
        // Notify approvers
        console.log("Submission requires approval");
      }

      // Process form values
      if (formSubmission.formName === "Quality Inspection") {
        const { passed, temperature, notes } = formSubmission.values as {
          passed: boolean;
          temperature: number;
          notes: string;
        };

        if (!passed) {
          // Trigger quality alert
          console.log(`Quality check failed: ${notes}`);
        }
      }
      break;
  }
}