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
- Getting Started
- Running Services
- Sending Data to Services
- Managing Services
- Service Features
- Role Based Access Control
- Logging and Events
- Multi-Cloud Databases
- Multi-Cloud File Storage
Choosing a Programming Language
You may select new languages while creating or editing a service.
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
Source Code: https://hook.io/marak/echo/_src
If you require the source code of a Hook to remain private, upgrade to a paid account and set the Hook to
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
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
Nested parameters are also supported.
Data can also be sent via form POST
To send streaming data to the hook, simply open up a streaming http request.
To send data to a Hook over Websocket, simply connect to the endpoint using any
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.
Uses a built-in Code Editor and stores source code of the service in hook.io
Pulls the source code of the service from a Github Repository.
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.
Hook will be the first function argument and
Hook.req will be streams. For other programming languages,
Hook will be defined globally in the script 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
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
22.214.171.124 ( 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.
Based on the
Content-Type header, hook.io will process the incoming request differently.
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.
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.
Will attach any multipart file uploads as streams to Hook.params. File uploads can then be handled as streams inside the Hook.
Will treat the incoming request as a binary data stream.
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
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.
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.
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
curl to execute hot-code against hook.io's gateway.
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 GatewaysNote: Most gateways will an return an error or blank response if the
sourceparameter is not provided
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.
SSL / HTTPS
HTTPS is supported on hook.io through a single shared
All URLs and services on the site are available over
If you require a custom
SSL certificate for your microservices, please contact firstname.lastname@example.org
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.
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 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