Location Events

Network operators send real-time notifications to RSP-provided webhook endpoints when location data changes. This push-based model ensures RSPs receive updates immediately without polling.

Event Types

• LOCATION_CREATED - New location added to system
• LOCATION_UPDATED - Existing location modified

Webhook Endpoint

RSPs must implement this endpoint to receive location change notifications:

POST {rsp_webhook_url}/locations/events

Headers

Header	Description	Required
Content-Type	Must be application/json	Yes
X-Event-Id	Event UUID for deduplication	Yes
X-Event-Type	Event type (e.g., LOCATION_UPDATED)	Yes
X-Event-Timestamp	ISO 8601 timestamp of event (UTC with Z suffix)	Yes

Request Body

{
  "event": {
    "id": "987fcdeb-51a2-4567-89ab-123456789012",
    "type": "LOCATION_CREATED",
    "timestamp": "2025-06-08T14:22:00Z",
    "source": "network-operator-system",
    "data": {
      // Complete location object
    },
    "modifiedFields": {
      // Only for LOCATION_UPDATED events
    }
  }
}

Expected Responses

Status	Meaning	Network Operator Action
200 OK	Event processed successfully	Mark as delivered
202 Accepted	Event queued for processing	Mark as delivered
400 Bad Request	Invalid event data	Do not retry
401 Unauthorized	Authentication failed	Check credentials, retry
429 Too Many Requests	Rate limit exceeded	Retry with backoff
500 Internal Server Error	RSP system error	Retry with backoff

Event Structure

All location events follow the standard Open Access Forum event wrapper format.

Common Event Fields

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

Modified Fields

For LOCATION_UPDATED events, the modifiedFields property contains only the groups and fields that changed:

{
  "event": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "LOCATION_UPDATED",
    "timestamp": "2025-06-08T14:22:00Z",
    "source": "network-operator-system",
    "data": { /* Complete Location */ },
    "modifiedFields": {
      "fiberAccessDetails": {
        "serviceability": {
          "status": "ACTIVE",
          "availableDate": "2025-08-15"
        }
      }
    }
  }
}

Event Examples

Location Created Event

New apartment building added to the network:

{
  "event": {
    "id": "567abc89-0def-1234-5678-9abcdef01234",
    "type": "LOCATION_CREATED",
    "timestamp": "2025-06-08T10:00:00Z",
    "source": "network-management-system",
    "data": {
      "id": "678def90-1234-5678-9abc-def012345678",
      "createdAt": "2025-06-08T10:00:00Z",
      "updatedAt": "2025-06-08T10:00:00Z",
      "geography": {
        "country": "US",
        "region": "TX",
        "locality": "ROUND ROCK",
        "postalCode": "78665"
      },
      "address": {
        "streetNumber": "1000",
        "streetName": "MAIN",
        "streetType": "STREET",
        "subunitType": "APARTMENT",
        "subunitIdentifier": "101"
      },
      "fiberAccessDetails": {
        "serviceability": {
          "status": "CONSTRUCTION",
          "availableDate": "2025-08-15"
        }
      }
    }
  }
}

Location Status Update Event

Location activated after construction completion:

{
  "event": {
    "id": "789cde01-2345-6789-abcd-ef0123456789",
    "type": "LOCATION_UPDATED",
    "timestamp": "2025-08-15T14:30:00Z",
    "source": "network-management-system",
    "data": {
      "id": "678def90-1234-5678-9abc-def012345678",
      "createdAt": "2025-06-08T10:00:00Z",
      "updatedAt": "2025-08-15T14:30:00Z",
      "geography": {
        "country": "US",
        "region": "TX",
        "locality": "ROUND ROCK",
        "postalCode": "78665"
      },
      "address": {
        "streetNumber": "1000",
        "streetName": "MAIN",
        "streetType": "STREET",
        "subunitType": "APARTMENT",
        "subunitIdentifier": "101"
      },
      "fiberAccessDetails": {
        "serviceability": {
          "status": "ACTIVE",
          "availableDate": "2025-08-15"
        }
      }
    },
    "modifiedFields": {
      "fiberAccessDetails": {
        "serviceability": {
          "status": "ACTIVE",
          "availableDate": "2025-08-15"
        }
      }
    }
  }
}

Address Correction Event

Street name corrected after validation:

{
  "event": {
    "id": "890def12-3456-789a-bcde-f01234567890",
    "type": "LOCATION_UPDATED",
    "timestamp": "2025-06-09T11:15:00Z",
    "source": "address-validation-system",
    "data": {
      "id": "901efg23-4567-89ab-cdef-012345678901",
      "createdAt": "2025-01-15T09:00:00Z",
      "updatedAt": "2025-06-09T11:15:00Z",
      "geography": {
        "country": "US",
        "region": "TX",
        "locality": "AUSTIN",
        "postalCode": "78748"
      },
      "address": {
        "streetNumber": "5501",
        "streetDirection": "S",
        "streetName": "MOPAC EXPRESSWAY",
        "streetType": "EXPRESSWAY",
        "subunitType": "SUITE",
        "subunitIdentifier": "100"
      },
      "coordinates": {
        "latitude": 30.1905,
        "longitude": -97.8417
      },
      "fiberAccessDetails": {
        "serviceability": {
          "status": "ACTIVE",
          "availableDate": "2025-01-01"
        }
      }
    },
    "modifiedFields": {
      "address": {
        "streetName": "MOPAC EXPRESSWAY"
      }
    }
  }
}

Event Implementation Notes

Event Delivery

Network operators implement webhook delivery with the following characteristics:

1. Retry Logic - Failed deliveries are retried with exponential backoff
2. Timeout - Webhook calls timeout after 30 seconds
3. Ordering - Events are delivered in the order they occur when possible
4. Batching - Events are sent individually, not batched

Duplicate Handling

Events may be delivered multiple times due to network issues or retry logic. RSPs must handle duplicates by:

1. Using the event ID for deduplication
2. Implementing idempotent event processing

Error Handling

RSPs should implement robust error handling:

1. Client Errors (4xx) - Log the error and do not retry
2. Server Errors (5xx) - Queue for later processing and return 202 Accepted
3. Timeout Protection - Process events asynchronously to avoid timeouts
4. Graceful Degradation - Continue processing other events if one fails

Event Flow Diagram