LocalLive API

Webhooks are an efficient way for API users to receive notifications of changes in API data without having to constantly poll the API. When an event on our system occurs, like an event is booked, we will issue an HTTP POST request to a URL you specify. It will include a payload of POST data in the form of an array of key-value pairs. To register for webhooks you will need to contact LocalLive support.

Webhooks available:

   Event Booked
   Event Updated
   Event Status Changed

   Each webhook can be for all events, all events involving a particular school id, or all events involving a school in a particular school group.

   Each api user will have a secret key value for signing of the webhook call. We have included an explanation of webhook signing at the bottom of this document.

Event Booked and Updated Webhooks Payload

   eventID - event ID - int like 100000
   eventStatusID - int
   eventStatus - text like 'Archived'
   eventType - Sports | School
   sportID - int if sports event, null if school event
   sport - text name of sport or null if school event
   varsityLevelID - int or null is school event
   varsityLevel - text like 'Varsity' or null if school event
   genderID - 0=Male, 1=Female, 2=Mixed or null if school event
   genderText - text like 'Men's' or null if school event
   schoolEventTypeID - int if school event, null if sports event
   schoolEventType - text if school event, null if sports event
   title - text
   startTimeLocal - ISO 8601 datetime 2023-10-22T17:14:22+00:00
   endTimeLocal - ISO 8601 datetime 2023-10-22T17:14:22+00:00
   timezone - iana time zone like 'America/Chicago'
   tzAbbreviation - example EDT
   startTimeUTC - ISO 8601 datetime 2023-10-22T17:14:22+00:00
   endTimeUTC - ISO 8601 datetime 2023-10-22T17:14:22+00:00
   venueID - int
   venueName - text
   homeSchoolID - int
   homeSchoolName - text
   homeConferenceID - int or null for school event
   homeConference - text or null for school event
   awaySchoolID - int or null for school event
   awaySchoolName - text or null for school event
   awayConferenceID - int or null for school event
   passwordHash - will be null at time of booking
   isPrivate - null if not private or 1 if private, meaning we don't list this event on school schedules

Event Status Changed Webhook Payload

   ID - event ID - int like 100000
   eventStatusID - int
   eventStatus - text like 'Archived'
   hlsVideoUrl
         example: https://content.locallive.tv/manifests/C2PM0xlX.m3u8
         set as event goes live

HLS Video URL

HLS urls are meant for use in embedded video players for live and archived http streaming.
For download video links, use the api: http://api.locallive.tv/api/videos/event_id

Event Statuses

Available via API: https://api.locallive.tv/api/event-statuses

Sports

Available via API: https://api.locallive.tv/api/sports

Conferences

Available via API: https://api.locallive.tv/api/conferences

School Event Types

   Missing from API so listed here:    0 - Other
   1 - Athletics
   2 - Commencement
   3 - Assembly
   4 - Music
   5 - Performing Arts
   6 - Graduation
   7 - Memorial
   8 - Chapel
   9 - Meeting

IANA Time Zones

https://www.iana.org/time-zones https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

ISO 8601 Date and Time Format Explained:

   - Standard: ISO 8601.
   - Format: YYYY-MM-DDThh:mm:ss+zz:zz.
   - Components:
   - YYYY: Four-digit year (e.g., 2023).
   - MM: Two-digit month (01 to 12).
   - DD: Two-digit day of the month (01 to 31).
   - T: A delimiter separating the date and time components.
   - hh: Two-digit hour (00 to 23).
   - mm: Two-digit minutes (00 to 59).
   - ss: Two-digit seconds (00 to 59).
   - +zz:zz: The timezone offset from UTC (e.g., +00:00 represents Coordinated Universal Time).

Explanation of Webhook Signing

Webhook signing is a security measure to ensure that the data received from a webhook is indeed from the expected source and has not been tampered with. This is done by creating a signature using a secret key that both the sender (your Laravel API) and the receiver (the user of your API) know.

When your API sends a webhook, it generates a signature by hashing the payload with the secret key. The hashing algorithm used in this case is SHA-256. The generated signature is then included in the webhook request, typically in the headers.

The user's system, upon receiving the webhook, will generate its own hash of the received payload using the same secret key and compare it to the signature sent in the webhook. If the two signatures match, it confirms that the webhook is authentic and the data has not been altered.

Example in PHP

$signature = hash_hmac('sha256', $payloadJson, $secret);

Example in Python

import hmac
import hashlib

def create_signature(payload, secret):
return hmac.new(bytes(secret, 'utf-8'), bytes(payload, 'utf-8'), hashlib.sha256).hexdigest()

# Usage
signature = create_signature(payloadJson, secret)

Example in JavaScript (Node.js)

const crypto = require('crypto');

function createSignature(payload, secret) {
return crypto.createHmac('sha256', secret).update(payload).digest('hex');
}

// Usage
const signature = createSignature(JSON.stringify(payload), secret);

Example in Ruby

In Ruby, you can use the OpenSSL library for this purpose.
require 'openssl'

def create_signature(payload, secret)
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, payload)
end

# Usage
signature = create_signature(payload_json, secret)

API Documentation