Update: On 15.06.2016 the Event-API entered BETA state.
Abstract
This guide introduces the football-data API concept for providing push events, which in short free you from polling. Some of you may know this technique from Git where it is called webhook. However, as per my understanding 'hooks' only exist in the vocabulary of version control systems, I'll stick to the more general term '(push) event'.
From an architectural point of view the usage of that technique is sometimes considered as 'unclean' as it requires the participating parties to change roles: the client needs to implement server functionality (that is: a webserver) and the server needs to implement client functionality (that is: call a method on the client). As in my mind pragmatism always supersedes rules or standards or anything, let's just see how it works and what it exactly gives us.
I decided to expose some of the API internals where I use a more or less event based architecture. Some of the events (internally) fired are now publicly available so I'll first describe what these events are, how they look like and what they do followed by the steps to be done to take advantage of these events and trigger an action to your liking.
Public Events.
The underneath table describes the available events. These are available for 2 Recources: Competition and Fixture. Used format is JSON.
Event/Resource Structure/Fields Description
Competition.Update Timestamp: DateTime in ISO8601
Resource: Competition
Id: \d+
URI: Resource-Endpoint
Updates: [FIELD_NAME: {OLD_VALUE, NEW_VALUE} ]
Gets fired when a competition resource receives an update which can be one of:
  • the competition is initialized
  • leagueTable is generated
  • new schedules
  • a new current matchday is set
Fixture.Update Timestamp: DateTime in ISO8601
Resource: Fixture
Id: \d+
URI: Resource-Endpoint
Updates: [FIELD_NAME: [OLD_VALUE, NEW_VALUE] ]
Gets fired when a fixture receives an update which can be one of:
  • new score
  • new status
The Update-Field shows the resources' field(s) that got updated. If there is no old/new value, it's just the field mentioned and the stuff after the pipe is missing completely.
Here are some samples that show how these messages look like. To illustrate, a request with curl:
curl -XPOST 'http://yourdomain.com/football-data.events/' -d '{        
  "Timestamp": "2016-02-12T12:00:00", 
  "Resource": "Competition", 
  "Id": 424, 
  "URI": "http://api.football-data.org/v1/competitions/424",
  "Updates": "LeagueTable"
}

# -----

curl -XPOST 'http://yourdomain.com/football-data.events/' -d '
{
  "Timestamp": "2015-02-12T14:00:00", 
  "Resource": "Fixture",
  "Id": 147211,
  "URI": "http://api.football-data.org/v1/fixtures/147211", 
  "Updates": [
              {'Score': ['1:0', '1:1'] }, 
              {'Status': ['TIMED', 'IN_PLAY'] } 
             ]
}'
As you can see we neatly integrate in a RESTful architectural style by using a POST request, to CREATE a new Event-Resource.
Catching the Events
So as my system will call your system the first thing you need to do is verify you are the owner of it. Go to your settings page to do so.
Now you have to setup a routine that is able to pick up the event and do something. Or to stick in RESTful vocabulary: You have to implement an endpoint for the Event-Resource which is at least capable of creating Events on your side (if this creation is persistent is up to you).
The Events are published via an HTTP POST Request. You have to catch that Request and return a 200 OK (though 201 would be 'more' correct), so that is to say you have to setup a webserver that listens on a specific port, takes the request and returns a (successful) response.
Like always this can be done in a variety of ways. The most common might be running a webserver in conjunction with a PHP script. However, a few weeks ago I started to get way deeper in Google Go while refactoring some parts of the API and I like it very much, so here's some code that implements catching the event resource:
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type Event struct {
    Resource string
    Id       int
    Updates  string
    URI      string
}

func EventHandler(w http.ResponseWriter, req *http.Request) {
    e := Event{}
    json.NewDecoder(req.Body).Decode(&e)
    fmt.Fprintf(os.Stdout, "Resource "+e.Resource+" with id %v got update(s). "+e.Updates+"\n", e.Id)
}

func main() {
    fmt.Println("Starting up server. Listening for push events...")
    http.HandleFunc("/football-data.events", EventHandler)
    http.ListenAndServe(":8477", nil)
} 
As mentioned earlier alternatively you can also setup a webserver that is able to interpret PHP code. Take this two-liner to write events to a file.
<?php
    $json = (file_get_contents('php://input'));
    file_put_contents('event_output.txt', $json . "\n", FILE_APPEND);
?>
Of course these code snippets should just get you going. Writing the events to console or in a file most likely is not what you want to. What you want to is either update your database directly or just trigger your already implemented library to fire a request to the resource to receive the fresh data.
Last but not least, you can still (or again) use the realtime-guide to setup your personal AMQP-listener that will receive the very same events. TO BE IMPLEMENTED
Have a read on the API internals to know when and what triggers the events.
Any events you are missing? Tell me via mail: daniel ät football-data.org!