Deployments: loading...

Documentation

Getting Started

A Hook is single function or block of code represented by a unique URL.

The Hook can be executed by sending HTTP requests to this URL.

To see live examples of using Hooks visit the: Interactive Microservice Tutorial

To see example Hooks which you can fork visit: Examples


Choosing a Programming Language

hook.io supports writing services in other programming languages besides JavaScript.

  • Bash
  • Coffee-Script
  • JavaScript
  • Lua
  • PHP
  • Python
  • Perl
  • Ruby
  • Scheme
  • SmallTalk
  • Tcl

You may select new languages while creating or editing a service.

Click here for an Interactive Microservice Tutorial

Creating a Hook

To create a Hook visit: https://hook.io/new

Forking an existing Hook

To fork another Hook, simply add /fork to the url of the Hook you want to fork.

By specifying the fork parameter, you will be taken to a new page where you can start customizing your Fork.

Once a Hook is created the browser will redirect to the admin page for that Hook.

Try It Now: https://hook.io/examples/echo/fork

Many Examples To Fork From: https://hook.io/examples


Running a Hook

Hooks are automatically executed when an HTTP request is sent to the Hook's url.

This HTTP request can be sent from any source ( such as the browser, custom application, or the command line).

Important Note about Service Timeouts:

All hooks have a 10 second timeout value by default. If the execution of your service takes longer then this value, the client will receive a service timeout error message.

In the majority of cases, a time-out indicates that the service failed to end properly and usually indicates a programming error.

Attempting to run an HTTP or TCP server in a Hook will not work!
Hooks are microservices ( think functions ), not servers.

In some other cases, you may be dealing with transferring a larger amount of data from a third-party service and the default timeout of ten seconds is not long enough to complete the transmission.

If you think your service may require more than 10 seconds to execute, hook.io allows for Custom Timeouts per service.


View Hook Source

To view the source code of any Hook simply attach /_src to the Hook service url.

This will also work for the Hook's View and Presenter.

Source Code: https://hook.io/marak/echo/_src

Logs: https://hook.io/marak/echo/logs

Resource: https://hook.io/marak/echo/resource

View: https://hook.io/marak/echo/view

Presenter: https://hook.io/marak/echo/presenter

If you require the source code of a Hook to remain private, upgrade to a paid account and set the Hook to Private

Hook Admin Panel

To access the Administration page for a Hook simply attach /admin to the Hook service url.

This will only work for Hooks which you own.


Hook Debugging and Logs

hook.io provides a seamless streaming log service which Hooks can write to with console.log. Simply call console.log from inside the Hook source code and the logging statement will be saved.

Streaming log endpoints are available for real-time consumption on all Hook service urls as /logs.

Example: https://hook.io/marak/echo/logs

Complete logging documentation can be found at https://hook.io/logs


Sending data to the Hook

Data can be sent to a Hook through any methods HTTP supports.

The most common way to send data to a Hook is through the URL query string or posted through forms or binary data transfers.

Query String Data

To add a parameter via query string simply append it to the url of the Hook

Example: https://hook.io/marak/echo?foo=bar&hello=there&run=true

Nested parameters are also supported.

Example: https://hook.io/marak/echo?foo['bar']=one&foo['tar']=two&run=true

Form Data

Data can also be sent via form POST

Curl Example:

Streaming Data

To send streaming data to the hook, simply open up a streaming http request.

Here is an example of streaming data to a hook

Websockets

To send data to a Hook over Websocket, simply connect to the endpoint using any ws client

More detailed instructions can be found at https://hook.io/websockets


Editing Hook source code

There are three options for specifying the source code for a Hook. Source code can be set on the /admin page for the Hook. To quickly get started, we recommend Forking an existing service.

Code Editor

Uses a built-in Code Editor and stores source code of the service in hook.io

Github Repository

Pulls the source code of the service from a Github Repository.

Github Gist

Pulls the source code of the service from a Github Gist.


Accessing the Hook object inside your code

All services are populated with a Hook object containing many useful properties.

For JavaScript based services, Hook will be the first function argument and Hook.req and Hook.req will be streams. For other programming languages, Hook will be defined globally in the script and STDIN and STDOUT streams will be available. The best way to understand how this works is by looking at the examples.

Hook.params - Incoming HTTP request data ( query string and form fields )
Hook.req - Incoming http.IncomingMessage stream
Hook.res - Outgoing httpServer.ServerResponse stream
Hook.datastore - Contains methods for getting and setting key-values from the datastore
Hook.fs - Contains methods for using the Cloud Files API
Hook.sdk - Contains a reference copy of the hook.io-sdk
Hook.schema - Optional mschema for hook.params
Hook.env - Optional. Key / value pairs stored by the owner of the Hook. See: Setting Hook Environment
Hook.streaming - Boolean. Is the Hook.req still streaming data. For most browser requests, this will be false.


Using the Cloud Datastore

Hooks have access to a key-value cloud datastore which can be used to store ange manage persistent data. This is useful for storing persistent information which you may want to retrieve later.

Read more about cloud datastore: https://hook.io/datastore

Specifying Optional Schema

Through the use of mschema, it is possible to enable validation and default values for incoming hook parameters.

To create a schema for the incoming hook parameters, simply specify the schema property on the /admin page for the hook. HTTP params will then be available in Hook.params.

Documentation for mschema can be found here.


Using the Mutli-Cloud Virtual File System

Hooks have access to a robust multi-cloud virtual file-system which can be used to manage files across multiple adapters. This is useful for storing persistent files which you may want to retrieve later.

Read more about multi-cloud virtual file system: https://hook.io/files



Setting Hook Environment Variables

To set Hook Environment variables visit: https://hook.io/env

Arbitrary key / value pairs can be set on your account so that all your Hooks will have access to the pairs in the Hook.env variable.

This is useful for protecting private authorization credentials from public view ( such as an API key or password ).

After you have updated your environment variables they will be available in your hook's Hook.env


Setting Custom Domains

Custom domains are a great way to brand the appearance of your service with it's own unique domain name.

To add a Custom Domain, you will first need to set the domains A record to 159.203.77.62 ( which is the ip address of hook.io ).

After setting the A record in your domain's DNS manager, simply visit: https://hook.io/domains to complete the process by mapping any of your Hooks to the Custom Domain.


Content-Type Routing

Based on the Content-Type header, hook.io will process the incoming request differently.


application/json
Will buffer the incoming request in order to parse the body as JSON. Incoming JSON maps to Hook.params. Streaming the incoming request is no longer possible at this point.

application/x-www-form-urlencoded
Will buffer the incoming request in order to process form fields. Incoming form fields maps to Hook.params.Streaming the incoming request is no longer possible at this point.

multipart/form-data
Will attach any multipart file uploads as streams to Hook.params. File uploads can then be handled as streams inside the Hook.

application/octet-stream
Will treat the incoming request as a binary data stream.


Cache Controls

To ensure optimal execution speeds, hook.io can cache your Hook's source code and assets in memory.

Currently, these caching controls can be toggled by setting the mode property in the Hook's admin page to either Production or Development.

In Development mode, all Hook source code will be pulled from it's original source on every request. This is useful for Hooks which are in active development.

In Production mode, all Hook source code will be cached in memory. This ensures much faster execution speeds, but also means that any updates to the Hook's external sources will not be immediately loaded.



Rate Limiting

hook.io will limit the total amount of API requests made against every account. This includes all API endpoints and every execution of any Hooks associated with the account.

In the event the total amount of API requests exceeds the amount of requests allocated with the accounts plan, further requests will be rate-limited. To increase rate limits, you can upgrade the account to a larger plan or email support for a temporary reset.

Rate Limits will automatically reset at the start of every billing cycle.

Rate Limiting HTTP Headers

Every API response from hook.io will include special HTTP headers indicating the current status of Rate Limits and Concurrency Limits.

X-RateLimit-Limit - Total amount of requests allowed per cycle
X-RateLimit-Remaining - Total amount of requests remaining in cycle
X-RateLimit-Running - Total amount of actively running requests


Hook Concurrency Limitations

hook.io will limit the of total amount services running concurrently per account. This means that every account may only have a certain amount of services running at the exact same time. In the event that too many services are running concurrently per account, further incoming HTTP requests will be rate-limited until some of the running services complete.

To increase concurrency limits, you can upgrade the account to a larger plan or email support.


Custom Service Timeouts

All hooks have a 10000 millisecond timeout ( 10 second ) value by default. If the execution of your service takes longer than this value, the client will receive a service timeout error.

In the majority of cases, a time-out error indicates that the service failed to end properly and usually indicates a programming error. Attempting to run an HTTP or TCP server in a Hook will not work! Hooks are microservices ( think functions ), not servers.

In some other cases, you may be dealing with transferring a larger amount of data from a third-party service or communicating with a slow responding third-party service and the default timeout of ten seconds is not long enough to complete the transmission. If you think your service may require more than 10 seconds to execute, simply visit the /admin page for the Hook and set the form field for "Custom Timeout" in milliseconds. Note: A paid account may be required.



Hot-Code Execution Gateway

In most cases, you will want to save your service's source-code as a Hook.

In other situations, you may need to send code that has to be executed immediately and without any additional requests ( such as testing and developing hooks or executing dynamically created source code from a third-party service ).

Read more on https://hook.io/gateways

hook.io provides a hot-code gateway which allows users to send code to be executed immediately. In fact, if you look at the Interactive Example on the hook.io homepage, you will notice it is powered by several hot-code gateways ( a separate gateway for each specific programming language ).

Examples of using the Hot-Code Gateways

Here are two simple examples of using echo and curl to execute hot-code against hook.io's gateway.

JavasScript

echo 'module["exports"] = function helloWorld (h) { h.res.end("Hello world!"); };' | curl --data-urlencode source@- http://javascript.hook.io

Python

echo 'print "hello world"' | curl --data-urlencode source@- http://python.hook.io/

You can also simply open a url to the gateway like this: http://python.hook.io/?source=print "hello world"

Available Gateways

Note: Most gateways will an return an error or blank response if the source parameter is not provided

System Events

All actions on hook.io are tracked internally as System Events.

These events are useful for monitoring the actions your services are performing, and who is performing them.

The relation of System Events and Role Access

It's important to note that all hook.io events are available as Access Roles. This mapping allows granular role based key access per System Event.

Read More about Role Based Access Control



SSL / HTTPS

Currently, HTTPS is supported on hook.io through a single shared SSL certificate.

All URLs and services on the site are available over HTTPS

If you require a custom SSL certificate for your microservices, please contact hookmaster@hook.io



Using hook.io as an HTTP API

A graphical interface exists for all of hook.io's supported features at https://hook.io In some cases, you may want a third party script or client ( not your browser window ), to be able to access a specific hook.io platform feature ( such as logs, the datastore, or creating a new hook service ). Using hook.io's HTTP API, you can access any platform feature that is available in our web app.

To keep things simple ( and self documenting ), the routes in our web app are 1:1 with our API. The /datastore or /logs endpoints are well documented examples of how this works, but other endpoints like /new might require a small amount of reverse engineering.

hook.io SDK

An easy way to access the hook.io API programmatically is through the hook.io SDK. Read more on https://hook.io/sdk

API Access Keys

hook.io provides a robust role based API key access system.

All events on hook.io are registered as roles which can be granted per generated API access key

All API endpoints are backed by Role Based Access Control, so if you provide a hook_private_key parameter in your request which matches a known API key containing the required role that request will be granted access to the resource. Read More about Keys and Roles