NAV
shell ruby javascript

Introduction

Welcome to the Hosted Hooks API!

Hosted Hooks is a service to help you provide webhooks to your subscribers ( Webhooks as a Service).

When events are occuring in your app, you need a way to notify your subcribers. We help you do that by being your webhook provider.

  1. When events occur within your app you send a message to us via our API
  2. We ingest that message, queue it up and send it out to your subscribers
  3. We are constantly managing your subscriber's endpoints for downtime and errors

We have language bindings in Shell. Ruby and JavaScript are coming soon! You can view code examples in the dark area to the right.

If you have any questions, please reach out to support@hostedhooks.com

Authentication

To authorize, use this code:

  # Coming soon!
# With shell, you can just pass the correct header with each request
curl "https://www.hostedhooks.com/api/v1" \
  -H "Authorization: Bearer API_KEY"
  Coming soon!

Make sure to replace API_KEY with your API key.

Our uses API keys to allow access to the API. When you sign up your organization will be assigned a new Hosted Hooks API key. You can find yours in the settings portal.

We expect your API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer API_KEY

Apps

Apps are a way for you to organize your webhooks. As an organization you will be creating Apps (you can have many) and use those Apps to group collections of webhook_events and subscribers. When a subscriber wants to subscribe to your Webhooks, they will be subscribing to your App.

Get All Apps

  # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps" \
  -H "Authorization: Bearer API_KEY"
  Coming soon!

The above command returns JSON structured like this:

[
  {
    "id": "9fe10e24-455a-4089-b62d-539d46fa9302",
    "name": "ABC App",
    "created_at": "2021-03-23T08:19:38.943-04:00"
  },
  {
    "id": "0f6f3219-1c40-4a1f-bf2e-35e00b210c9f",
    "name": "Foo App",
    "created_at": "2021-03-23T08:19:38.943-04:00"
  }
]

This endpoint retrieves all apps for your organization.

HTTP Request

GET https://www.hostedhooks.com/api/v1/apps

Create App

  # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps" \
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -d json
  Coming soon!

The above command returns JSON structured like this:

{
  "id": "3fff6ea0-2e85-4af3-bf62-2246ed187b32",
  "name": "ABC App",
  "created_at": "2021-03-23T08:19:38.943-04:00"
}

This endpoint creates a new app for your organization.

Your organization can have many apps. When your webhook has subscribers, they will be subscribing to a specific app within your organization so keep that in mind when creating your apps.

HTTP Request

POST https://www.hostedhooks.com/api/v1/apps

Parameter Type Required Description
name string true This is the name of the App that you are creating

Edit App

  # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/:app_id" \
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -d json
  Coming soon!

The above command returns JSON structured like this:

{
  "id": "65fba83c-14e7-46aa-8790-b8c723d98bd3",
  "name": "ABC App",
  "created_at": "2021-03-23T08:19:38.943-04:00"
}

This endpoint updates an existing app for your organization.

HTTP Request

PATCH https://www.hostedhooks.com/api/v1/apps/:app_id

URL Parameters

Parameter Description
app_id This is the id of the App being edited

PATCH Parameters

Send as a JSON object

Parameter Type Required Description
name string true This is the name of the App that you are creating

Subscriptions

Subscriptions connect your subscribers to your App. A subscriber can only subscribe to your App and once subscribed they can create many endpoints.

Subscriptions can be created via:

Once a Subscription has been created, a user can be invited to that Subscription and they can log in to the Subscriber Portal.

Get All Subscriptions

 # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/1/endpoints" \
  -H "Authorization: Bearer API_KEY"
  Coming soon!

The above command returns JSON structured like this:

  [
    {
      "id": "c17f9d4f-52cd-4819-a0b3-e7b5ad68b761",
      "subscriber_name": "New Subscriber Company",
      "created_at": "2021-03-29T10:03:09.717-04:00",
      "app": {
        "id": "bd8ba9a4-05a3-4592-838c-4f98bc92e84f",
        "name": "Super Cool SaaS",
        "created_at": "2021-03-27T10:07:17.540-04:00"
      }
    }
  ]

This returns all Subscriptions for your App.

HTTP Request

GET https://www.hostedhooks.com/api/v1/apps/:app_id/subscriptions

Get Subscription

 # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/subscriptions/:subscription_id" \
  -H "Authorization: Bearer API_KEY"
  Coming soon!

The above command returns JSON structured like this:

  {
    "id": "c17f9d4f-52cd-4819-a0b3-e7b5ad68b761",
    "subscriber_name": "New Subscriber Company",
    "created_at": "2021-03-29T10:03:09.717-04:00",
    "app": {
      "id": "bd8ba9a4-05a3-4592-838c-4f98bc92e84f",
      "name": "Super Cool SaaS",
      "created_at": "2021-03-27T10:07:17.540-04:00"
    }
  }

This returns a single Subscription

HTTP Request

GET https://www.hostedhooks.com/api/v1/subscriptions/:subscription_id

Create Subscription

  # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/:app_id/subscriptions" \
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -d json
  Coming soon!

The above command returns JSON structured like this:

  {
    "id": "c17f9d4f-52cd-4819-a0b3-e7b5ad68b761",
    "subscriber_name": "New Subscriber Company",
    "created_at": "2021-03-29T10:03:09.717-04:00",
    "app": {
      "id": "bd8ba9a4-05a3-4592-838c-4f98bc92e84f",
      "name": "Super Cool SaaS",
      "created_at": "2021-03-27T10:07:17.540-04:00"
    }
  }

This POST creates a new subscription for your app.

Your app will have many subscriptions. These subscriptions are what connect your app to your subscribers.

HTTP Request

POST https://www.hostedhooks.com/api/v1/apps/:app_id/subscriptions

Parameter Type Required Description
name string true This is the name of the Subscribing organization

Endpoints

Endpoints hold all of the meta data for your Subscriber's integrations.

A subscriber can have many endpoints. They are created via:

Each Endpoint has a URL that points to your Subscriber's application and is the URL that we use as the destination for your webhooks.

Endpoints are created in an inactive state and need to be turned on.

Get All Endpoints

 # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/1/endpoints" \
  -H "Authorization: Bearer API_KEY"
  Coming soon!

The above command returns JSON structured like this:

[
   {
      "id":"4fc8e1f4-2d49-46ee-99a2-c8b942dd4c59",
      "url":"https://wwww.companyabc.com/webhooks",
      "description": "Shipping Company",
      "version":"1.0",
      "status":"active",
      "created_at":"2021-03-29T20:57:19.128-04:00",
      "webhook_events":[
         {
            "id":"1a8833ae-7d02-4855-b7fa-53d4aa7ef7f7",
            "event_type":"user.created",
            "created_at":"2021-03-27T10:07:17.608-04:00"
         }
      ],
      "subscription":{
         "id":"c17f9d4f-52cd-4819-a0b3-e7b5ad68b761",
         "subscriber_name":"New Subscriber Company",
         "created_at":"2021-03-29T10:03:09.717-04:00"
      }
   }
]

This returns all endpoints for your App.

HTTP Request

GET https://www.hostedhooks.com/api/v1/apps/:app_id/endpoints

Get Endpoint

 # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/1/endpoints/:endpoint_id" \
  -H "Authorization: Bearer API_KEY"
  Coming soon!

The above command returns JSON structured like this:

  {
     "id":"4fc8e1f4-2d49-46ee-99a2-c8b942dd4c59",
     "url":"https://wwww.companyabc.com/webhooks",
     "description": "Shipping Company",
     "version":"1.0",
     "status":"active",
     "created_at":"2021-03-29T20:57:19.128-04:00",
     "webhook_events":[
        {
           "id":"1a8833ae-7d02-4855-b7fa-53d4aa7ef7f7",
           "event_type":"user.created",
           "created_at":"2021-03-27T10:07:17.608-04:00"
        }
     ],
     "subscription":{
        "id":"c17f9d4f-52cd-4819-a0b3-e7b5ad68b761",
        "subscriber_name":"New Subscriber Company",
        "created_at":"2021-03-29T10:03:09.717-04:00"
     }
  }

This returns a single Endpoint

HTTP Request

GET https://www.hostedhooks.com/api/v1/apps/:app_id/endpoints/:endpoint_id

Create Endpoint

  # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/:app_id/endpoints" \
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -d json
  Coming soon!

The above command returns JSON structured like this:

  {
     "id":"4fc8e1f4-2d49-46ee-99a2-c8b942dd4c59",
     "url":"https://wwww.companyabc.com/webhooks",
     "description": "Shipping Company",
     "version":"1.0",
     "status":"active",
     "created_at":"2021-03-29T20:57:19.128-04:00",
     "webhook_events":[
        {
           "id":"1a8833ae-7d02-4855-b7fa-53d4aa7ef7f7",
           "event_type":"user.created",
           "created_at":"2021-03-27T10:07:17.608-04:00"
        }
     ],
     "subscription":{
        "id":"c17f9d4f-52cd-4819-a0b3-e7b5ad68b761",
        "subscriber_name":"New Subscriber Company",
        "created_at":"2021-03-29T10:03:09.717-04:00"
     }
  }

This POST creates a new endpoint for your app.

Your app will have many endpoints. These endpoints are the webhook destinations for your subscribers.

HTTP Request

POST https://www.hostedhooks.com/api/v1/apps/:app_id/endpoints

Parameter Type Required Description
url string true This is the url destination on your subscribers application where your webhooks will be sent
enabled_events array true These are the webhook events that you want the endpoint to receive updates on. You can also pass a '*' to subscribe to all webhook events for this app.
version string true The version of your webhooks that this endpoint is currently subscribed to. Use this to push non breaking changes
description string false A description of the endpoint
status string false The endpoints can either be in an active or inactive state. By default endpoints are created in an inactive state.

Edit Endpoint

  # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/:app_id/endpoints/:endpoint_id" \
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -d json
  Coming soon!

The above command returns JSON structured like this:

  {
     "id":"4fc8e1f4-2d49-46ee-99a2-c8b942dd4c59",
     "url":"https://wwww.companyabc.com/webhooks",
     "description": "Shipping Company",
     "version":"1.0",
     "status":"active",
     "created_at":"2021-03-29T20:57:19.128-04:00",
     "webhook_events":[
        {
           "id":"1a8833ae-7d02-4855-b7fa-53d4aa7ef7f7",
           "event_type":"user.created",
           "created_at":"2021-03-27T10:07:17.608-04:00"
        }
     ],
     "subscription":{
        "id":"c17f9d4f-52cd-4819-a0b3-e7b5ad68b761",
        "subscriber_name":"New Subscriber Company",
        "created_at":"2021-03-29T10:03:09.717-04:00"
     }
  }

This PATCH edits an existing endpoint for your app.

HTTP Request

POST https://www.hostedhooks.com/api/v1/apps/:app_id/endpoints/:endpoint_id

URL Parameters

Parameter Description
app_id This is the id of the App that the endpoint belongs to
endpoint_id This is the id of the endpoint that is being updated

PATCH Parameters

Send as a JSON object

Parameter Type Required Description
url string true This is the url destination on your subscribers application where your webhooks will be sent
enabled_events array true These are the webhook events that you want the endpoint to receive updates on. You can also pass a '*' to subscribe to all webhook events for this app.
version string true The version of your webhooks that this endpoint is currently subscribed to. Use this to push non breaking changes
description string false A description of the endpoint
status string false The endpoints can either be in an active or inactive state. By default endpoints are created in an inactive state.

Webhook Events

Webhook Events are the internal events happening within your app that you are notifying your subscribers about.

These are things like a new user being created or an order being shipped.

The value is a unique string (per app) and can be something like order_shipped or namespaced to orders.shipped, it's up to you.

Once you create these webhook events your webhook subscribers pick and choose which events they want to receive updates on. When the event occurs in your app and you want to notify your subscribers, you will use the Message POST endpoint and pass in this webhook event type.

Get All Webhook Events

 # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/1/webhook_events" \
  -H "Authorization: Bearer API_KEY"
  Coming soon!

The above command returns JSON structured like this:

[
  {
    "id": "9fe10e24-455a-4089-b62d-539d46fa9302",
    "event_type": "user.created",
    "created_at": "2021-03-23T08:19:38.943-04:00"
  },
  {
    "id": "0f6f3219-1c40-4a1f-bf2e-35e00b210c9f",
    "event_type": "order.confirmed",
    "created_at": "2021-03-23T08:19:38.943-04:00"
  }
]

This endpoint returns all webhook events for your App.

HTTP Request

GET https://www.hostedhooks.com/api/v1/apps/:id/webhook_events

Create Webhook Event

  # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/:app_id/webhook_events" \
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -d json
  Coming soon!

The above command returns JSON structured like this:

{
  "id": "9894550b-3b75-4bfc-b5b4-57732bddeef4",
  "event_type": "user.created",
  "created_at": "2021-03-23T08:19:38.943-04:00"
}

This endpoint creates a new webhook event for your app. These events are a unique string (per app) and can be something like order_shipped or namespaced to orders.shipped, it's up to you.

HTTP Request

POST https://www.hostedhooks.com/api/v1/apps/:app_id/webhook_events

URL Parameters

Parameter Description
app_id This is the id of the App

POST Parameters

Send as a JSON object

Parameter Type Required Description
event_type string true This is the name of the event

Messages

Messages are how your application will notify us of an event that has occurred.

Your app sends us a message via the API, we ingest it, queue it and send it out to your subscribers.

The Message object has a data payload which is a JSON blob that can you can customize as you need.

Everything included in that data payload will be sent directly to your Subscribers.

If you send your Message to one of your Apps, we will use the event_type to determine which Susbcribers should receive that Webhook. Every Subscriber that is subscribed to that event_type will receive a webhook.

If you don't want to send a Message to all Subscribers then you should send the Message using the specific Endpoint ID

The event_id parameter is used to maintain idempotency. This is a custom value that you should be generating and storing on your end. When you send us a new message, make sure it is a unique event_id as we will only ingest and save unique event_ids per App.

Create A Message (App)

 # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/apps/:app_id/messages" \
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -d json
  Coming soon!

The above command returns JSON structured like this:

{
  "id": "a2c12bd6-e147-4a28-aba6-e031345895ab",
  "data": {
    "foo": "bar"
  },
  "event_type": "user.created",
  "version": "1.0",
  "event_id": "12323124151",
  "created_at": "2021-03-23T08:19:38.943-04:00"
}

This creates a Message in the system for specific event. All subscribers of your App that are subscribed to the event will receive a webhook notification.

HTTP Request

POST https://hostedhooks.com/api/v1/apps/:id/messages

URL Parameters

Parameter Description
app_id This is the id of the App

POST Parameters

Send as a JSON object

Parameter Type Required Description
event_type string true This is the event that occurred in your system and will be used to trigger a notification to your subscribers. These need to match exactly how they are created in the dashboard.
data json true This is a json data structure to pass in any data that you want passed on to your webhook subscriber
version string true This is the version of the payload that is being sent in this request. You can update the payload and create new versions by updating this string. The subscriber will be directed to check the version when they ingest the webhook message.
event_id string false This is a custom id to make sure we don't ingest duplicate messages. Generate and store this ID on your end.

Create A Message (Endpoint)

 # Coming Soon!
curl "https://www.hostedhooks.com/api/v1/subscriptions/:subscription_id/endpoints/:endpoint_id/messages" \
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -d json
  Coming soon!

The above command returns JSON structured like this:

{
  "id": "65fba83c-14e7-46aa-8790-b8c723d98bd3",
  "data": {
    "foo": "bar"
  },
  "event_type": "user.created",
  "version": "1.0",
  "event_id": "12323124151",
  "created_at": "2021-03-23T08:19:38.943-04:00"
}

This creates a Message in the system for specific event. Only the subscriber that this endpoint belongs to will be notified of this event if the event type matches. All other subscribers of your App will not receive this message.

HTTP Request

POST https://hostedhooks.com/api/v1/subscriptions/:subscription_id/endpoints/:endpoint_id/messages

URL Parameters

Parameter Description
subscription_id This is the id of the Subscription
endpoint_id This is the id of the Endpoint

POST Parameters

Send as a JSON object

Parameter Type Required Description
event_type string true This is the event that occurred in your system and will be used to trigger a notification to your subscribers. These need to match exactly how they are created in the dashboard.
data json true This is a json data structure to pass in any data that you want passed on to your webhook subscriber
version string true This is the version of the payload that is being sent in this request. You can update the payload and create new versions by updating this string. The subscriber will be directed to check the version when they ingest the webhook message.
event_id string false This is a custom id to make sure we don't ingest duplicate messages. Generate and store this ID on your end.

Errors

The Hosted Hooks API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
429 Too Many Requests -- You're making too many requests.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.