Feedbird API

Feedbird (Program Engine) generates program/feed data and pushes it to Databird via webhooks. It focuses exclusively on sports data generation, events, markets, odds, and navigation structure.

Overview

Feedbird is responsible for:

Generating sports data, events, markets, and odds
Creating navigation and program structure
Providing real-time and scheduled event information
Pushing data updates to Databird via webhooks

Important: The frontend does NOT communicate directly with Feedbird. All program data flows through Databird, which receives webhooks from Feedbird and serves the data to the frontend.

Webhook Integration

Feedbird pushes program data to Databird via webhook endpoints. See the Databird API documentation for webhook endpoint details, authentication requirements, and payload structures.

Webhook Endpoints Provided by Databird

POST /v1/webhooks/program/liveEvents - Push live events updates
POST /v1/webhooks/program/hourEvents - Push hour events updates
POST /v1/webhooks/program/recommendedEvents - Push recommended events updates
POST /v1/webhooks/program/navigationTree - Push navigation tree updates
POST /v1/webhooks/program/topCompetitions - Push top competitions updates
POST /v1/webhooks/program/topCombos - Push top combos updates

Webhook Security

All webhook requests must include:

HMAC Signature: X-Webhook-Signature header with HMAC-SHA256 signature
Idempotency Key: Idempotency-Key header with UUID v4

See the Databird webhook documentation for detailed security requirements.

Direct GET Endpoints (Optional)

Feedbird may expose direct GET endpoints for other consumers (not used by the frontend). These endpoints mirror the structure of the webhook payloads and can be used for:

Monitoring and debugging
Third-party integrations
Data validation

Note: These endpoints are optional and not part of the standard frontend integration flow. The frontend should always use Databird endpoints.

Data Flow

Feedbird generates program data (events, markets, odds, navigation)
Feedbird pushes data to Databird via webhooks with HMAC signatures
Databird receives, validates, and aggregates the data
Frontend polls Databird GET endpoints to retrieve program data

Responsibilities

Responsibility	Feedbird	Databird	Frontend
Generate feed data	✅	❌	❌
Push data via webhooks	✅	❌	❌
Receive webhooks	❌	✅	❌
Aggregate program data	❌	✅	❌
Serve program endpoints	❌	✅	❌
Poll program endpoints	❌	❌	✅

Implementation Notes

Webhook Payload Structure

Webhook payloads sent by Feedbird should match the response structure of the corresponding GET endpoints in Databird:

Live Events: Matches GET /v1/program/events/live response structure
Hour Events: Matches GET /v1/program/events/hourEvents/{hour} response structure
Recommended Events: Matches GET /v1/program/recommendedEvents response structure
Navigation Tree: Matches GET /v1/program/navigationTree/all response structure
Top Competitions: Matches GET /v1/program/top-competitions response structure
Top Combos: Matches GET /v1/program/top-combos response structure

Timestamp Requirements

All webhook payloads must include a timestamp field (ISO 8601 format) to prevent replay attacks:

{
  "LIVE_WIDGET": {...},
  "timestamp": "2024-01-15T14:30:00Z"
}

Retry Logic

Feedbird should implement exponential backoff retry logic for webhook delivery failures. See the Databird webhook documentation for recommended retry strategies.

Feedbird API

On this page