Event Structure

Open Access Forum APIs use a standardized event wrapper for webhook-based real-time updates.

Event Wrapper Format

{
  "event": {
    "id": "string (UUID)",
    "type": "string",
    "timestamp": "string (ISO 8601)",
    "source": "string",
    "data": {},
    "modifiedFields": {}
  }
}

Field Definitions

Field	Required	Type	Description
id	Yes	UUID	Unique identifier for the event
type	Yes	string	Event type in UPPER_SNAKE_CASE (e.g., LOCATION_CREATED)
timestamp	Yes	ISO 8601	When the event occurred (with timezone)
source	Yes	string	Identifier of the system generating the event
data	Yes	object	Complete current state of the resource
modifiedFields	No	object	Sparse object containing only changed fields for UPDATE events

Event Types

Event types should follow the pattern: {RESOURCE}_{ACTION}

Examples:

• LOCATION_CREATED
• LOCATION_UPDATED
• LOCATION_DELETED
• ORDER_SUBMITTED
• ORDER_COMPLETED

Modified Fields

For UPDATE events, include a sparse representation of what changed:

{
  "event": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "LOCATION_UPDATED",
    "timestamp": "2025-06-08T14:22:00Z",
    "source": "network-operator-system",
    "data": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2025-06-01T10:30:00Z",
      "updatedAt": "2025-06-08T14:22:00Z",
      "geography": {
        "country": "US",
        "region": "TX",
        "locality": "AUSTIN",
        "postalCode": "78701"
      },
      "address": {
        "streetNumber": "1234",
        "streetDirection": "N",
        "streetName": "CONGRESS",
        "streetType": "AVENUE"
      },
      "fiberAccessDetails": {
        "serviceability": {
          "status": "ACTIVE",
          "availableDate": "2025-06-01"
        }
      }
    },
    "modifiedFields": {
      "fiberAccessDetails": {
        "serviceability": {
          "status": "ACTIVE"
        }
      }
    }
  }
}

Expected Responses

• 200 OK - Event successfully received
• 202 Accepted - Event queued for processing
• 4xx/5xx - Delivery failed, will retry