Skip to main content

​
Webhooks

Receive real-time notifications when orbital events occur, including conjunctions, anomalies, and pattern detections.
Status: Coming Q1 2026 — Request early access to be notified when available.

​
Overview

Webhooks deliver events to your application in real-time:
  • Conjunction alerts — New conjunctions or risk level changes
  • Pattern detections — Maneuvers, anomalies, proximity events
  • Satellite updates — Status changes, new TLE data
  • System events — API maintenance, data source updates

​
Quick Start

from rotastellar import RotaStellar

client = RotaStellar(api_key="rs_...")

# Create a webhook endpoint
webhook = client.webhooks.create(
    url="https://your-app.com/rotastellar-events",
    events=["conjunction.created", "conjunction.risk_changed", "pattern.detected"],
    secret="your-webhook-secret"
)

print(f"Webhook ID: {webhook.id}")
print(f"Status: {webhook.status}")

​
Event Types

​
Conjunction Events

EventDescription
conjunction.createdNew conjunction detected
conjunction.updatedConjunction parameters updated
conjunction.risk_changedRisk level changed
conjunction.resolvedConjunction passed or maneuver executed

​
Pattern Events

EventDescription
pattern.detectedNew pattern identified
pattern.maneuverManeuver specifically detected
pattern.anomalyAnomaly specifically detected
pattern.proximityProximity operation detected

​
Satellite Events

EventDescription
satellite.tle_updatedNew orbital elements available
satellite.status_changedOperational status changed
satellite.decay_warningReentry prediction issued

​
Webhook Payload

All webhook payloads follow this structure: 
{
  "id": "evt_abc123",
  "type": "conjunction.created",
  "timestamp": "2026-01-21T12:00:00Z",
  "data": {
    "conjunction": {
      "id": "conj_xyz789",
      "tca": "2026-01-23T14:32:15Z",
      "primary": {
        "id": "12345",
        "name": "STARLINK-1234"
      },
      "secondary": {
        "id": "45678",
        "name": "COSMOS 2251 DEB"
      },
      "miss_km": 0.45,
      "probability": 2.3e-5,
      "risk_level": "HIGH"
    }
  }
}

​
Verifying Webhooks

Verify webhook signatures to ensure authenticity: 
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler
@app.post("/rotastellar-events")
def handle_webhook(request):
    signature = request.headers.get("X-RotaStellar-Signature")
    payload = request.body

    if not verify_webhook(payload, signature, "your-webhook-secret"):
        return {"error": "Invalid signature"}, 401

    event = json.loads(payload)
    print(f"Received event: {event['type']}")

    return {"status": "ok"}

​
Managing Webhooks

​
List Webhooks

webhooks = client.webhooks.list()

for wh in webhooks:
    print(f"{wh.id}: {wh.url}")
    print(f"  Events: {', '.join(wh.events)}")
    print(f"  Status: {wh.status}")

​
Update Webhook

webhook = client.webhooks.update(
    id="wh_abc123",
    events=["conjunction.created", "pattern.anomaly"],  # Change events
    enabled=True
)

​
Delete Webhook

client.webhooks.delete("wh_abc123")

​
Test Webhook

Send a test event to verify your endpoint: 
result = client.webhooks.test("wh_abc123")

print(f"Test result: {result.status}")
print(f"Response time: {result.response_time_ms}ms")

​
Filtering Events

Filter events to specific satellites: 
# Only receive events for specific satellites
webhook = client.webhooks.create(
    url="https://your-app.com/events",
    events=["conjunction.created", "pattern.detected"],
    filters={
        "satellites": ["SAT-001", "SAT-002", "SAT-003"]
    }
)
Filter by risk level: 
# Only receive HIGH and CRITICAL conjunctions
webhook = client.webhooks.create(
    url="https://your-app.com/alerts",
    events=["conjunction.created", "conjunction.risk_changed"],
    filters={
        "risk_levels": ["HIGH", "CRITICAL"]
    }
)

​
Retry Policy

Failed webhook deliveries are retried with exponential backoff:
AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours
68 hours
After 6 failed attempts, the webhook is disabled and you’ll receive an email notification.

​
Best Practices

Return a 2xx response within 30 seconds. Process events asynchronously if needed.
Events may be delivered more than once. Use the event id to deduplicate.
Always verify the X-RotaStellar-Signature header to ensure authenticity.
Webhook endpoints must use HTTPS for security.

​
Next Steps

Conjunction Analysis

Learn about conjunction events

Pattern Detection

Learn about pattern events