Introduction

Welcome to Hooks! Get familiar with our datasources and learn how to create subscriptions and configure a webhook:

Getting started

Hooks delivers real-time updates about thousands of topics in our datasources using webhooks. That way you can receive all our realtime data in your system exactly when it happens.

Our datasources include topics from 10 categories and growing.

Subscriptions

Hooks lets you subscribe to the data you need in your application:

  • Tomorrow is going to rain in Orihuela.
  • Real Madrid just won a match vs FC Barcelona
  • Bitcoin is now worth more than $10000
  • There is new article in Techcrunch RSS Feed

Once the new data is available we will call your webhook and send all the detailed information about the event. For the above rain subscription example your webhook will receive:

[
    {
        "_entity_type": "WeatherStatus",
        "_id": "WeatherStatus_Geoname_2513076-1518267600",
        "city": {
            "_entity_type": "City",
            "_id": "Geoname_2513076",
            "admin1_code": "60",
            "admin2_code": "A",
            "admin3_code": "03099",
            "admin4_code": null,
            "alternative_names": [
                "Auraiola",
                "Aurariola",
                "Orihuela",
                "Oriola",
                "Oriouela",
                "Oriuehla",
                "Oriuela",
                "Orivela",
                "ao li wei la",
                "aryhwyla",
                "awrywyla",
                "oriuera",
                "\u039f\u03c1\u03b9\u03bf\u03c5\u03ad\u03bb\u03b1",
                "\u041e\u0440\u0438\u0432\u0435\u043b\u0430",
                "\u041e\u0440\u0438\u0443\u044d\u043b\u0430",
                "\u041e\u0440\u0456\u0443\u0435\u043b\u0430",
                "\u0555\u0580\u056b\u0578\u0582\u0565\u056c\u0561",
                "\u0623\u0648\u0631\u064a\u0648\u064a\u0644\u0627",
                "\u0627\u0631\u06cc\u0647\u0648\u0626\u0644\u0627",
                "\u0627\u0648\u0631\u06cc\u06c1\u06cc\u0648\u0644\u0627",
                "\u30aa\u30ea\u30a6\u30a8\u30e9",
                "\u5965\u91cc\u97e6\u62c9"
            ],
            "ascii_name": "Orihuela",
            "coordinates": "38.08483,-0.94401",
            "country": {
                "country_code_2": "ES",
                "country_code_3": "ESP",
                "country_numeric_code": "724",
                "name": "Spain",
                "official_name": "Kingdom of Spain"
            },
            "dem": "32",
            "elevation": null,
            "feature_class": "P",
            "feature_code": "PPLA3",
            "geonameid": "2513076",
            "id": "Geoname_2513076",
            "modification_date": "2012-03-04",
            "name": "Orihuela",
            "population": 86164,
            "subdivision": {
                "country_code_2": "ES",
                "name": "Valenciana, Comunidad \/ Valenciana, Comunitat",
                "subdivision_code": "ES-VC",
                "type": "Autonomous community"
            },
            "timezone": "Europe\/Madrid"
        },
        "features": {
            "clouds_percent": 20,
            "humidity_percent": 28,
            "pressure": {
                "hPa": 1020,
                "inHg": 30.12,
                "mmHg": 765.06
            },
            "rain": {
                "inch_hour": 0,
                "mm_hour": 0
            },
            "snow": {
                "inch_hour": 0,
                "mm_hour": 0
            },
            "temperature": {
                "celsius": 13.66,
                "fahrenheit": 32
            },
            "wind_direction_degrees": 320,
            "wind_speed": {
                "meters_per_second": 7.7,
                "miles_per_hour": 17.22
            }
        },
        "is_current": true,
        "measure_time": {
            "countdown": -2847,
            "datetime": "2018-02-10T13:00:00+0000",
            "timestamp": 1518267600
        },
        "start_datetime": {
            "countdown": -2847,
            "datetime": "2018-02-10T13:00:00+0000",
            "timestamp": 1518267600
        },
        "weather_conditions": [
            {
                "description": "few clouds",
                "icon": "02d",
                "icon_url": "http:\/\/openweathermap.org\/img\/w\/02d",
                "id": 801,
                "main": "Clouds"
            }
        ]
    }
]


Customizing subscription

Hooks provides an elegant mechanism for creating subscriptions using Hooks Query Language. It has a similar notation to SQL and lets you define each subscription with a simple HQL query.

The HQL query for the above example, Tomorrow is going to rain in , is:

SELECT * 
FROM WeatherByCity(name='Madrid' and country.name='Spain') 
WHERE weather_conditions.main = "Rain"


Creating subscription

Once you define your HQL query, your code makes an API request to create a subscription on our servers:

curl -H "Content-type: application/json" -d '{
	"query": "SELECT * FROM WeatherByCity(name=\'Madrid\' and country.name=\'Spain\') WHERE features.temperature.celsius < 20"
}' 'http://api.hooksdata.io/v1/subscriptions'

Hooks will then call your webhook once new data is available for your query.


Next steps