Maintenance provider

Receive aircraft maintenance alerts and create work orders in your shop-management system. Suitable when your destination system has a work-order API and you operate as the maintenance provider for one or more consumer organizations.

Scopes needed

Scope	Why	Alternative if too broad
public.maintenance:read	Read the due-items table and work-order list for the consumer org.	None — required.
public.fleet:read	Join alerts to the aircraft registration and current airworthiness state.	Drop if you store the fleet map externally; relies only on registration in the payload.

Data flow

bash

┌────────────────────┐     ┌─────────────────┐
│ webhook delivery   │ ──▶ │ verify HMAC sig │
│ maintenance.alert  │     └────────┬────────┘
└────────────────────┘              │
                                    ▼
                       ┌────────────────────────┐
                       │ dedupe on Delivery-UUID│
                       └───────────┬────────────┘
                                   │
                                   ▼
                       ┌────────────────────────┐
                       │ create work-order in   │
                       │ your shop system       │
                       └───────────┬────────────┘
                                   │
                                   ▼
                       ┌────────────────────────┐
                       │ store link in your DB  │
                       └────────────────────────┘

Implementation

1. Webhook handler — create a work order on alert:

// Pseudo-code — webhook handler creates a work order on alert.
app.post("/webhooks/gaflight", verifyHmac, async (req, res) => {
  const delivery = req.header("X-GA-Webhook-Delivery");
  if (await alreadyProcessed(delivery)) return res.status(204).end();

  const { type, data } = req.body.event;
  if (type === "maintenance.alert") {
    const wo = await shop.createWorkOrder({
      externalId: `gaflight:${data.alertId}`,
      aircraft: data.registration,
      reason: data.dueItemDescription,
      severity: data.severity,        // "warning" | "overdue"
    });
    await markProcessed(delivery, wo.id);
  }
  res.status(204).end();
});

2. Reconcile — periodically list open due-items to catch missed deliveries:

bash

# Periodically reconcile against the platform — catches missed deliveries.
curl "https://api.gaflight.io/api/v1/public/maintenance/due?status=open&limit=100" \
  -H "Authorization: Bearer gaf_pk_<token>" \
  -H "X-Org-Id: <consumer-org-uuid>"

3. Close-loop — write-back is not yet available in v2.1 read-only:

// When a work order is completed in your shop, write back the link via
// a future write scope. v2.1 is read-only — for now, hold the closure
// reference in your shop system and rely on the partner to mark the
// due-item resolved manually inside the GA Flight console.

Edge cases

Duplicate alerts: dedupe on the X-GA-Webhook-Delivery header before you create a work order.
Multi-org consumers: the installation_id (header on every delivery) tells you which consumer org fired the alert; key your shop accounts by it.
Retry storms after your downtime: the platform retries up to 5 times with exponential backoff; your handler must remain idempotent during the burst.
Status divergence: alerts may be acknowledged in the console before your shop completes the work order; do NOT auto-close on a follow-up compliance.updated.
Severity escalation: an open alert can flip warning→overdue between deliveries; bump the priority on your existing work order rather than creating a second.
Aircraft retirement: fleet:read returns retired aircraft too; filter status='active' before opening shop accounts.
Time zones: due-item timestamps are UTC; render in the consumer's local tz where it matters operationally.

Going live

Declare the two scopes above on your developer app with ≥40-char justifications each.
Stand up the webhook receiver with HMAC verification and X-GA-Webhook-Delivery dedupe BEFORE submitting your listing.
Submit your listing for review (see /developers/review-policy).
Publish under your org and share the install URL with shop customer organizations.
Document the alert-to-work-order mapping policy in your customer-facing runbook.

Generic template

This recipe is a generic implementation pattern. No real integration partner is named or endorsed. Substitute your own backend, terminology, and customer fit as appropriate.

Looking for the full interactive reference?

Open API Reference →

Recipe

Maintenance provider

Scopes needed

Scope	Why	Alternative if too broad
public.maintenance:read	Read the due-items table and work-order list for the consumer org.	None — required.
public.fleet:read	Join alerts to the aircraft registration and current airworthiness state.	Drop if you store the fleet map externally; relies only on registration in the payload.

Data flow

bash

┌────────────────────┐     ┌─────────────────┐
│ webhook delivery   │ ──▶ │ verify HMAC sig │
│ maintenance.alert  │     └────────┬────────┘
└────────────────────┘              │
                                    ▼
                       ┌────────────────────────┐
                       │ dedupe on Delivery-UUID│
                       └───────────┬────────────┘
                                   │
                                   ▼
                       ┌────────────────────────┐
                       │ create work-order in   │
                       │ your shop system       │
                       └───────────┬────────────┘
                                   │
                                   ▼
                       ┌────────────────────────┐
                       │ store link in your DB  │
                       └────────────────────────┘

Implementation

1. Webhook handler — create a work order on alert:

// Pseudo-code — webhook handler creates a work order on alert.
app.post("/webhooks/gaflight", verifyHmac, async (req, res) => {
  const delivery = req.header("X-GA-Webhook-Delivery");
  if (await alreadyProcessed(delivery)) return res.status(204).end();

  const { type, data } = req.body.event;
  if (type === "maintenance.alert") {
    const wo = await shop.createWorkOrder({
      externalId: `gaflight:${data.alertId}`,
      aircraft: data.registration,
      reason: data.dueItemDescription,
      severity: data.severity,        // "warning" | "overdue"
    });
    await markProcessed(delivery, wo.id);
  }
  res.status(204).end();
});

2. Reconcile — periodically list open due-items to catch missed deliveries:

bash

# Periodically reconcile against the platform — catches missed deliveries.
curl "https://api.gaflight.io/api/v1/public/maintenance/due?status=open&limit=100" \
  -H "Authorization: Bearer gaf_pk_<token>" \
  -H "X-Org-Id: <consumer-org-uuid>"

3. Close-loop — write-back is not yet available in v2.1 read-only:

// When a work order is completed in your shop, write back the link via
// a future write scope. v2.1 is read-only — for now, hold the closure
// reference in your shop system and rely on the partner to mark the
// due-item resolved manually inside the GA Flight console.

Edge cases

Duplicate alerts: dedupe on the X-GA-Webhook-Delivery header before you create a work order.
Multi-org consumers: the installation_id (header on every delivery) tells you which consumer org fired the alert; key your shop accounts by it.
Retry storms after your downtime: the platform retries up to 5 times with exponential backoff; your handler must remain idempotent during the burst.
Status divergence: alerts may be acknowledged in the console before your shop completes the work order; do NOT auto-close on a follow-up compliance.updated.
Severity escalation: an open alert can flip warning→overdue between deliveries; bump the priority on your existing work order rather than creating a second.
Aircraft retirement: fleet:read returns retired aircraft too; filter status='active' before opening shop accounts.
Time zones: due-item timestamps are UTC; render in the consumer's local tz where it matters operationally.

Going live

Declare the two scopes above on your developer app with ≥40-char justifications each.
Stand up the webhook receiver with HMAC verification and X-GA-Webhook-Delivery dedupe BEFORE submitting your listing.
Submit your listing for review (see /developers/review-policy).
Publish under your org and share the install URL with shop customer organizations.
Document the alert-to-work-order mapping policy in your customer-facing runbook.

Generic template

This recipe is a generic implementation pattern. No real integration partner is named or endorsed. Substitute your own backend, terminology, and customer fit as appropriate.