Docs
CLI
API
Guides
Concepts
Platforms
Try for Free

Introduction

Getting StartedPagingErrorsQuery Formating

Resources

Webhook ConnectionsSourcesDestinationsRulesetsEventsAttemptsBulkBookmarks

More

Get In Touch

Getting Started

Welcome to the Hookdeck Admin REST API! Our API allows you to set up your connections, retrieve your events and perform various actions such as retries. Explore our data, browse the descriptions of the available attributes and see examples of working requests and responses.

Create your account

To use the API, you'll need an API key that you can retrieve from your account. Sign in or sign up at https://hookdeck.com/signin. Each workspace is assigned a unique API key used to authenticate with Hookdeck.

Authentication

Use Basic Authentication to authorize your request. The username is your API Key and the password is blank:

Hookdeck uses API keys via Basic Auth to allow access to the API. You can retrieve your Hookdeck API key in your dashboard.

Hookdeck expects your API key to be included in all your API requests to the server in the header. It would look like the following:

Authorization: Basic BASE64_API_TOKEN

curl "https://api.hookdeck.com/events"
  -H "Content-Type: application/json"
  -u "${YOUR_API_KEY}:"

Create your first connection

When you create your first webhook, you can pass a destination and source definition. Along with the request, all the required resources will be created. When a webhook is created without a ruleset, the default ruleset is applied.

Mandatory parameters

Webhook

Parameter Type Description
label string Name of the webhook

Source

Parameter Type Description
label string Name of the source

Destination

One of url or cli_path is mandatory

Parameter Type Description
label string Name of the destination
url url Endpoint of the destination
cli_path string Path for the CLI destination

The body returns an ID for the source, the destination, and the ruleset generated for the webhook. They can be reused by passing the destination_id, source_id, or ruleset_id instead of an object.

POST
https://api.hookdeck.com/connections

Request Body

{
  "alias": "shopify-my-api",
  "source": {
    "label": "Shopify",
    "alias": "shopify"
  },
  "destination": {
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook"
  }
}

Response Example

{
  "id": "web_cYAEhzTwVM8IKrSB26CYiO12",
  "label": "Shopify → My API",
  "alias": "shopify-my-api",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.503Z",
  "created_at": "2021-01-21T23:54:33.503Z",
  "filters": null,
  "destination": {
    "id": "des_5el1duGBVKlxReLQ1BKCWXeE",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook",
    "cli_path": null,
    "rate_limit": 5,
    "rate_limit_period": "second",
    "archived_at": null,
    "updated_at": "2021-01-21T23:54:33.442Z",
    "created_at": "2021-01-21T23:54:33.410Z"
  },
  "source": {
    "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Shopify",
    "alias": "shopify",
    "archived_at": null,
    "updated_at": "2021-01-21T23:54:33.443Z",
    "created_at": "2021-01-21T23:54:33.411Z",
    "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
  },
  "ruleset": {
    "id": "rls_2wx4z178zk82c4hhn",
    "alias": null,
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Default Ruleset 1",
    "retry_count": 5,
    "retry_interval": 60000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2020-11-16T03:38:09.554Z",
    "created_at": "2020-03-22T01:00:37.647Z",
    "alert_interval": 60000,
    "alert_strategy": null
  }
}

Example reusing a resource

{
  "label": "Shopify to My API",
  "alias": "shopify-my-api",
  "destination_id": "des_xxxxxxxxxxxxxxx",
  "source_id": "src_xxxxxxxxxxxxxxx",
  "ruleset_id": "rls_xxxxxxxxxxxxxxx"
}

Update your endpoint

Update the endpoint on your source with the Hookdeck's unique URL.

The connection URL is a property of the webhook connection object

{
  "id": "web_xxxxxxxxxxxxxxx",
  "url": "https://events.hookdeck.com/e/src_xxxxxxxxxxxxxxx",
  [...]
}

Monitoring

All webhooks events that are handled by Hookdeck can be viewed, inspected, filtered, sorted, manually retried, and much more from the dashboard or with the API.

Paging

All GET endpoints to retrieve a list of resources are paged using cursor (keyset, seek) pagination.

To work with Cursor paging all the necessary information will be contained in the response body pagination object.

Parameter Default Description
order_by "created_at" The sortable key to use (options varies base on the resource )
dir "desc" The direction to sort it ("asc" or "desc")
limit 100 The making amount of results returned per query (max: 250)
next undefined The ID to provide in the query to get the next set of results
prev undefined The ID to provide in the query to get the previous set of results
next undefined The cursor to provide in the query to get the next set of results
previous undefined The cursor to provide in the query to get the previous set of results

Unless you have specified an order_by or dir, you can omit it from the next or previous set query. You only have to carry them over if you are not using the resource default.

Example pagination object:

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100,
    "next": "web_2urj7h9puxk6obro3x",
    "prev": "web_2urj7h9puxk6obuf6i"
  }
}

Example to get the next page:

curl "https://api.hoockdeck.com/connections?next=web_2urj7h9puxk6obro3x"
  -H "Authorization: Basic BASE64_API_TOKEN"

Example to get the previous page:

curl "https://api.hoockdeck.com/connections?previous=web_2urj7h9puxk6obuf6i"
  -H "Authorization: Basic BASE64_API_TOKEN"

Example to get the next page without using the default ordering:

curl "https://api.hoockdeck.com/connections?order_by=updated_at&dir=asc&next=web_2urj7h9puxk6obro3x"
  -H "Authorization: Basic BASE64_API_TOKEN"

Errors

Hookdeck uses standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing), and codes in the 5xx range indicate an error.

Response

With any HTTP error, the response body will contain a few properties.

Parameter Type Description
handle boolean Error was handled by the API and did not resolve in an uncaught exception.
status integer HTTP Status of the error
message string Message associated with the error, could be more or less specific depending on the error
data object Data related to the error, useful for diagnostics

Error Codes

Status Code Explanation
200 Good Request -- Your request is valid.
400 Bad Request -- Your request is invalid and could not be understood.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested access is restricted.
404 Not Found -- The resource could not be found.
422 Unprocessable Entry -- Your request was understood but contains invalid input.
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.

Example response from an error

{
  "handled": true,
  "status": 422,
  "message": "Webhook does not exist or is archived",
  "data": {
    "id": "web_xxxxxxxxxxx"
  }
}

Query Formating

Arrays

Arrays are supported for query parameters indicated by [] appended to their type. Ex: string[]

Arrays should be encoded as ?item[1]=hello&item[2]=world which will be parse to ["hello", "world"]

Date

Dates are expected to be in ISO format ex: 2021-01-21T20:16:28Z or 2021-01-21.

JSON

Some query params take JSON as input. The JSON should be stringified and URL encoded into a string.

ex: ?body=%7B%0A%20%20"hello"%3A%20"world"%0A%7D which will be parse to { "hello": "world" }

Operators

Most query parameters for GET endpoints to retrieve a list of resources support query operators. The operators are:

Parameter Supported Types Description
gte date number Greater or equal then
gt date number Greater then
lte date number Lesser or equal then
lt date number Lesser then
any date number string Not null

Example pagination object:

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100,
    "next": "web_2urj7h9puxk6obro3x",
    "prev": "web_2urj7h9puxk6obuf6i"
  }
}

Example to get the next page:

curl "https://api.hoockdeck.com/connections?next=web_2urj7h9puxk6obro3x"
  -H "Authorization: Basic BASE64_API_TOKEN"

Example to get the previous page:

curl "https://api.hoockdeck.com/connections?previous=web_2urj7h9puxk6obuf6i"
  -H "Authorization: Basic BASE64_API_TOKEN"

Example to get the next page without using the default ordering:

curl "https://api.hoockdeck.com/connections?order_by=updated_at&dir=asc&next=web_2urj7h9puxk6obro3x"
  -H "Authorization: Basic BASE64_API_TOKEN"

Webhook Connections

A webhook connection is used to join a source, a destination, and a ruleset.

Endpoints

GET
https://api.hookdeck.com/connections

GET
https://api.hookdeck.com/connections/:id

POST
https://api.hookdeck.com/connections

PUT
https://api.hookdeck.com/connections

PUT
https://api.hookdeck.com/connections/:id

Webhook Connection object

Parameter Type Default Description
id string ID of the connection
label string Label of the connection
alias string A unique, human friendly id for the source
team_id string ID of the workspace
source Source Associated Source object
destination Destination Associated Destination object
ruleset Ruleset Workspace default ruleset Associated Ruleset object
archived_at ISO Date null Date the webhook was archived
updated_at ISO Date Last ISO Date the webhook was updated
created_at ISO Date Date the webhook was created 
{
  "id": "web_5b3mzbxk83c8qml",
  "label": "Shopify to My API",
  "alias": "shopify-my-api",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "archived_at": null,
  "updated_at": "2020-03-22T17:51:42.286Z",
  "created_at": "2020-03-22T17:51:42.290Z",
  "source": {
    "id": "src_5b3mzbxk83c8qky",
    "team_id": "tm_5b3mzbxk83c0k7i",
    "label": "Shopify",
    "alias": "shopify",
    "description": null,
    "archived_at": null,
    "updated_at": "2020-03-22T17:51:42.229Z",
    "created_at": "2020-03-22T17:51:42.231Z",
    "url": "https://events.hookdeck.com/e/src_5b3mzbxk83c8qky"
  },
  "destination": {
    "id": "des_5b3mzbxk83c8qkr",
    "team_id": "tm_5b3mzbxk83c0k7i",
    "label": "My API",
    "alias": "my-api",
    "description": null,
    "url": "https://example.com/webhook",
    "cli_path": "/webhook",
    "rate_limit": 5,
    "rate_limit_period": "second",
    "archived_at": null,
    "updated_at": "2020-03-22T17:51:42.228Z",
    "created_at": "2020-03-22T17:51:42.231Z"
  },
  "ruleset": {
    "id": "rls_5b3mzbxk83c0k89",
    "alias": "default-ruleset",
    "team_id": "tm_5b3mzbxk83c0k7i",
    "label": "Default Ruleset",
    "description": null,
    "retry_count": 5,
    "retry_interval": 3600000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2020-03-22T17:45:20.742Z",
    "created_at": "2020-03-22T17:45:20.746Z"
  }
}

Retrieve all webhook connections

Query Parameter

Parameter Type Description
id string[] Filter by connection ids
archived boolean Include the archived resources in response
archived_at date Date the connection was archived
limit number Limit the returned event count. Max 250.
GET
https://api.hookdeck.com/connections

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "web_cXXoHcVQRsqquknyfrhjEtns"
  },
  "count": 1,
  "models": [
    {
      "id": "web_cXXoHcVQRsqquknyfrhjEtns",
      "label": "Shopify → My API",
      "alias": "shopify-my-api",
      "team_id": "tm_2wx4z178zk82c4hh9",
      "archived_at": null,
      "updated_at": "2021-01-21T23:53:41.797Z",
      "created_at": "2021-01-21T23:53:41.796Z",
      "filters": null,
      "destination": {
        "id": "des_1hg4DlAaBTTigG8oWU4lLmpu",
        "team_id": "tm_2wx4z178zk82c4hh9",
        "label": "My API",
        "alias": "my-api",
        "url": "https://example.com/webhook",
        "cli_path": "/webhook",
        "rate_limit": 5,
        "rate_limit_period": "second",
        "archived_at": null,
        "updated_at": "2021-01-21T23:53:41.732Z",
        "created_at": "2021-01-21T23:53:41.706Z"
      },
      "source": {
        "id": "src_ogpVC7H1uxjr03tQkLu2F5DH",
        "team_id": "tm_2wx4z178zk82c4hh9",
        "label": "Shopify",
        "alias": "shopify",
        "archived_at": null,
        "updated_at": "2021-01-21T23:53:41.733Z",
        "created_at": "2021-01-21T23:53:41.706Z",
        "url": "https://events.hookdeck.com/e/src_ogpVC7H1uxjr03tQkLu2F5DH"
      },
      "ruleset": {
        "id": "rls_2wx4z178zk82c4hhn",
        "alias": null,
        "team_id": "tm_2wx4z178zk82c4hh9",
        "label": "Default Ruleset 1",
        "retry_count": 5,
        "retry_interval": 60000,
        "retry_strategy": "linear",
        "is_team_default": true,
        "archived_at": null,
        "updated_at": "2020-11-16T03:38:09.554Z",
        "created_at": "2020-03-22T01:00:37.647Z",
        "alert_interval": 60000,
        "alert_strategy": null
      }
    }
  ]
}

Retrieve a webhook connection

URL Parameter

Parameter Description
id Webhook ID
GET
https://api.hookdeck.com/connections/:id

Response Example

{
  "id": "web_te6bgdS4X6i5f5xcczTYDwey",
  "label": "Fast Retry Ruleset → My API",
  "alias": "fast-retry-ruleset-my-api",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "archived_at": null,
  "updated_at": "2021-01-21T23:53:41.692Z",
  "created_at": "2021-01-21T22:51:38.361Z",
  "filters": null,
  "destination": {
    "id": "des_64ykD0Ep6tpM8Aw0xRcrwNgU",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook",
    "cli_path": "/webhook",
    "rate_limit": 5,
    "rate_limit_period": "second",
    "archived_at": null,
    "updated_at": "2021-01-21T22:51:38.319Z",
    "created_at": "2021-01-21T22:51:38.295Z"
  },
  "source": {
    "id": "src_gpL3jyaCIKYGODnxWhl5piha",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Fast Retry Ruleset",
    "alias": "fast-retry-ruleset",
    "archived_at": null,
    "updated_at": "2021-01-21T23:11:54.028Z",
    "created_at": "2021-01-21T23:11:54.003Z",
    "url": "https://events.hookdeck.com/e/src_gpL3jyaCIKYGODnxWhl5piha"
  },
  "ruleset": {
    "id": "rls_2wx4z178zk82c4hhn",
    "alias": null,
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Default Ruleset 1",
    "retry_count": 5,
    "retry_interval": 60000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2020-11-16T03:38:09.554Z",
    "created_at": "2020-03-22T01:00:37.647Z",
    "alert_interval": 60000,
    "alert_strategy": null
  }
}

Create a webhook connection

Body Parameters

Parameter Type Description
label string Custom connection label. Otherwise will default to a concatenation of the source and destination label
alias string A unique, human friendly id for the source
source_id string ID of a source to bind to the connection
destination_id string ID of a destination to bind to the connection
ruleset_id string ID of a rule to bind to the connection. Default to the Workspace default ruleset
source Source Source input object
destination Destination Destination input object
ruleset Ruleset Ruleset input object

Create a webhook connection with new resources

You can create a webhook connection with its underlying source, destination, and ruleset with a single call by including an object for any of those resources.

Create a connection with existing resources

You can reuse a source, a destination, or a ruleset when creating a webhook connection by referencing their ID.

POST
https://api.hookdeck.com/connections

Request Body

{
  "alias": "shopify-my-api",
  "source": {
    "label": "Shopify",
    "alias": "shopify"
  },
  "destination": {
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook"
  }
}

Response Example

{
  "id": "web_cYAEhzTwVM8IKrSB26CYiO12",
  "label": "Shopify → My API",
  "alias": "shopify-my-api",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.503Z",
  "created_at": "2021-01-21T23:54:33.503Z",
  "filters": null,
  "destination": {
    "id": "des_5el1duGBVKlxReLQ1BKCWXeE",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook",
    "cli_path": null,
    "rate_limit": 5,
    "rate_limit_period": "second",
    "archived_at": null,
    "updated_at": "2021-01-21T23:54:33.442Z",
    "created_at": "2021-01-21T23:54:33.410Z"
  },
  "source": {
    "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Shopify",
    "alias": "shopify",
    "archived_at": null,
    "updated_at": "2021-01-21T23:54:33.443Z",
    "created_at": "2021-01-21T23:54:33.411Z",
    "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
  },
  "ruleset": {
    "id": "rls_2wx4z178zk82c4hhn",
    "alias": null,
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Default Ruleset 1",
    "retry_count": 5,
    "retry_interval": 60000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2020-11-16T03:38:09.554Z",
    "created_at": "2020-03-22T01:00:37.647Z",
    "alert_interval": 60000,
    "alert_strategy": null
  }
}

Creating a webhook connection with a new source and destination

{
  "alias": "github-some-api",
  "source": {
    "label": "Gitub",
    "alias": "github"
  },
  "destination": {
    "label": "Some API",
    "alias": "some-api",
    "url": "https://example.com/webhook"
  }
}

Creating a connection by reusing a source or a destination

{
  "source_id": "src_xxx",
  "destination_id": "des_xxx"
}

Create/Update a webhook connection

This endpoint creates a webhook connection or updates an existing webhook connection by alias. A webhook connection's source and destination cannot be updated.

Body Parameters

You can create a webhook connection with its underlying source, destination, and ruleset with a single call by including an object for any of those resources.

Parameter Type Description
label string Custom connection label. Otherwise will default to a concatenation of the source and destination label
alias string A unique, human friendly id for the
source_id string ID of a source to bind to the connection
destination_id string ID of a destination to bind to the connection
ruleset_id string ID of a rule to bind to the connection. Default to the Workspace default ruleset
source Source Source input object
destination Destination Destination input object
ruleset Ruleset Ruleset input object
PUT
https://api.hookdeck.com/connections

Request Body

{
  "alias": "shopify-my-api",
  "source": {
    "label": "Shopify",
    "alias": "shopify"
  },
  "destination": {
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook"
  }
}

Response Example

{
  "id": "web_cYAEhzTwVM8IKrSB26CYiO12",
  "label": "Shopify → My API",
  "alias": "shopify-my-api",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.503Z",
  "created_at": "2021-01-21T23:54:33.503Z",
  "filters": null,
  "destination": {
    "id": "des_5el1duGBVKlxReLQ1BKCWXeE",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook",
    "rate_limit": 5,
    "rate_limit_period": "second",
    "archived_at": null,
    "updated_at": "2021-01-21T23:54:33.442Z",
    "created_at": "2021-01-21T23:54:33.410Z"
  },
  "source": {
    "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Shopify",
    "alias": "shopify",
    "archived_at": null,
    "updated_at": "2021-01-21T23:54:33.443Z",
    "created_at": "2021-01-21T23:54:33.411Z",
    "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
  },
  "ruleset": {
    "id": "rls_2wx4z178zk82c4hhn",
    "alias": null,
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Default Ruleset 1",
    "retry_count": 5,
    "retry_interval": 60000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2020-11-16T03:38:09.554Z",
    "created_at": "2020-03-22T01:00:37.647Z",
    "alert_interval": 60000,
    "alert_strategy": null
  }
}

Update a webhook connection

This endpoint updates a webhook connection.

URL Parameter

Parameter Description
id Webhook ID

Body Parameters

Parameter Type Description
label string Custom connection label
ruleset_id string ID of a rule to bind to the connection. Default to the Workspace default ruleset
ruleset Ruleset Ruleset input object
PUT
https://api.hookdeck.com/connections/:id

Request Body

{
  "ruleset_id": "rls_5b3mzbxk83c0k89"
}

Response Example

{
  "id": "web_te6bgdS4X6i5f5xcczTYDwey",
  "label": "Fast Retry Ruleset → My API",
  "alias": "fast-retry-ruleset-my-aPI",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.396Z",
  "created_at": "2021-01-21T22:51:38.361Z",
  "filters": null,
  "destination": {
    "id": "des_64ykD0Ep6tpM8Aw0xRcrwNgU",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook",
    "cli_path": "/webhook",
    "rate_limit": 5,
    "rate_limit_period": "second",
    "archived_at": null,
    "updated_at": "2021-01-21T22:51:38.319Z",
    "created_at": "2021-01-21T22:51:38.295Z"
  },
  "source": {
    "id": "src_gpL3jyaCIKYGODnxWhl5piha",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Fast Retry Ruleset",
    "alias": "fast-retry-ruleset",
    "archived_at": null,
    "updated_at": "2021-01-21T23:11:54.028Z",
    "created_at": "2021-01-21T23:11:54.003Z",
    "url": "https://events.hookdeck.com/e/src_gpL3jyaCIKYGODnxWhl5piha"
  },
  "ruleset": {
    "id": "rls_2wx4z178zk82c4hhn",
    "alias": null,
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Default Ruleset 1",
    "retry_count": 5,
    "retry_interval": 60000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2020-11-16T03:38:09.554Z",
    "created_at": "2020-03-22T01:00:37.647Z",
    "alert_interval": 60000,
    "alert_strategy": null
  }
}

Archive a connection

This endpoint archives a connection. A archived connection will no longer receive or deliver any webhooks.

URL Parameter

Parameter Description
id Connection ID
PUT
https://api.hookdeck.com/connections/:id/archive

Response Example

{
  "id": "web_te6bgdS4X6i5f5xcczTYDwey",
  "label": "Fast Retry Ruleset → My API",
  "alias": "fast-retry-ruleset-my-api",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "archived_at": "2021-01-21T23:54:33.396Z",
  "updated_at": "2021-01-21T23:54:33.396Z",
  "created_at": "2021-01-21T22:51:38.361Z",
  "filters": null,
  "destination": {
    "id": "des_64ykD0Ep6tpM8Aw0xRcrwNgU",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook",
    "cli_path": "/webhook",
    "rate_limit": 5,
    "rate_limit_period": "second",
    "archived_at": null,
    "updated_at": "2021-01-21T22:51:38.319Z",
    "created_at": "2021-01-21T22:51:38.295Z"
  },
  "source": {
    "id": "src_gpL3jyaCIKYGODnxWhl5piha",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Fast Retry Ruleset",
    "alias": "fast-retry-ruleset",
    "archived_at": null,
    "updated_at": "2021-01-21T23:11:54.028Z",
    "created_at": "2021-01-21T23:11:54.003Z",
    "url": "https://events.hookdeck.com/e/src_gpL3jyaCIKYGODnxWhl5piha"
  },
  "ruleset": {
    "id": "rls_2wx4z178zk82c4hhn",
    "alias": null,
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Default Ruleset 1",
    "retry_count": 5,
    "retry_interval": 60000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2020-11-16T03:38:09.554Z",
    "created_at": "2020-03-22T01:00:37.647Z",
    "alert_interval": 60000,
    "alert_strategy": null
  }
}

Unarchive a connection

This endpoint unarchives a connection. The associated source/destination will also be unarchived if they were previously archived.

URL Parameter

Parameter Description
id Connection ID
PUT
https://api.hookdeck.com/connections/:id/unarchive

Response Example

{
  "id": "web_te6bgdS4X6i5f5xcczTYDwey",
  "label": "Fast Retry Ruleset → My API",
  "alias": "fast-retry-ruleset-my-api",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.396Z",
  "created_at": "2021-01-21T22:51:38.361Z",
  "filters": null,
  "destination": {
    "id": "des_64ykD0Ep6tpM8Aw0xRcrwNgU",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "My API",
    "alias": "my-api",
    "url": "https://example.com/webhook",
    "cli_path": "/webhook",
    "rate_limit": 5,
    "rate_limit_period": "second",
    "archived_at": null,
    "updated_at": "2021-01-21T22:51:38.319Z",
    "created_at": "2021-01-21T22:51:38.295Z"
  },
  "source": {
    "id": "src_gpL3jyaCIKYGODnxWhl5piha",
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Fast Retry Ruleset",
    "alias": "fast-retry-ruleset",
    "archived_at": null,
    "updated_at": "2021-01-21T23:11:54.028Z",
    "created_at": "2021-01-21T23:11:54.003Z",
    "url": "https://events.hookdeck.com/e/src_gpL3jyaCIKYGODnxWhl5piha"
  },
  "ruleset": {
    "id": "rls_2wx4z178zk82c4hhn",
    "alias": null,
    "team_id": "tm_2wx4z178zk82c4hh9",
    "label": "Default Ruleset 1",
    "retry_count": 5,
    "retry_interval": 60000,
    "retry_strategy": "linear",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2020-11-16T03:38:09.554Z",
    "created_at": "2020-03-22T01:00:37.647Z",
    "alert_interval": 60000,
    "alert_strategy": null
  }
}

Sources

The Source object represents the third party sending the webhooks. Each source will provide you with a unique Hookdeck URL where the webhooks can be set to be ingested by Hookdeck. Each valid HTTP request received at that URL creates an Event.

Endpoints

GET
https://api.hookdeck.com/sources

GET
https://api.hookdeck.com/sources/:id

POST
https://api.hookdeck.com/sources

PUT
https://api.hookdeck.com/sources

PUT
https://api.hookdeck.com/sources/:id

PUT
https://api.hookdeck.com/sources/:id/archive

PUT
https://api.hookdeck.com/sources/:id/unarchive

Source object

Parameter Type Default Description
id string ID of the source
team_id string ID of the workspace
label string Name of the source
alias string A unique, human friendly id for the source
archived_at date null Date the source was archived
updated_at date ISO Last ISO Date the source was updated
created_at date ISO Date the source was created

Using the source URL

The source object contains a url that must be provided to your webhook's provider. The URL serves as your 'webhook url'.

{
  "id": "src_1b69dxk87s0g4k",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "label": "Shopify Production",
  "alias": "shopify-prod",
  "archived_at": null,
  "updated_at": "2020-03-25T20:46:26.742Z",
  "created_at": "2020-03-25T20:24:14.069Z",
  "url": "https://events.hookdeck.com/e/src_1b69dxk87s0g4k"
}

Retrieve all sources

Query Parameter

Parameter Type Description
id string[] Filter by source ids
alias string The source alias
archived boolean Include the archived resources in response
archived_at date Date the source was archived
limit number Limit the returned event count. Max 250.
GET
https://api.hookdeck.com/sources

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "src_cnsv4W1wixpFDvACwAAlkLCi"
  },
  "count": 1,
  "models": [
    {
      "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
      "team_id": "tm_2wx4z178zk82c4hh9",
      "label": "Shopify",
      "alias": "shopify",
      "archived_at": null,
      "updated_at": "2021-01-21T23:54:33.443Z",
      "created_at": "2021-01-21T23:54:33.411Z",
      "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
    }
  ]
}

Retrieve a source

URL Parameter

Parameter Description
id Webhook ID
GET
https://api.hookdeck.com/sources/:id

Response Example

{
  "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Shopify",
  "alias": "shopify",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T23:54:33.411Z",
  "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
}

Create a source

This endpoint creates a source.

Body Parameters

Parameter Type Description
label string Name of the source
alias string A unique, human friendly id for the source
POST
https://api.hookdeck.com/sources

Request Body

{
  "label": "Shopify",
  "alias": "shopify"
}

Response Example

{
  "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Shopify",
  "alias": "shopify",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T23:54:33.411Z",
  "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
}

Create/Update a source

This endpoint creates a source or updates an existing source by alias.

Body Parameters

Parameter Type Description
label string Name of the source
alias string A unique, human friendly id for the source
PUT
https://api.hookdeck.com/sources

Request Body

{
  "label": "Shopify",
  "alias": "shopify"
}

Response Example

{
  "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Shopify",
  "alias": "shopify",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T23:54:33.411Z",
  "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
}

Update a source

This endpoint creates a source.

URL Parameter

Parameter Description
id Webhook ID

Body Parameters

Parameter Type Description
label string Name of the source
alias string A unique, human friendly id for the source
PUT
https://api.hookdeck.com/sources/:id

Request Body

{
  "label": "Shopify"
}

Response Example

{
  "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Shopify",
  "alias": "shopify",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T23:54:33.411Z",
  "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
}

Archive a source

This endpoint archives a source and any associated webhook connections.

URL Parameter

Parameter Description
id Source ID
PUT
https://api.hookdeck.com/sources/:id/archive

Response Example

{
  "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Shopify",
  "alias": "shopify",
  "archived_at": "2021-01-21T23:54:33.454Z",
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T23:54:33.411Z",
  "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
}

Unarchive a source

URL Parameter

Parameter Description
id Source ID
PUT
https://api.hookdeck.com/sources/:id/unarchive

Response Example

{
  "id": "src_cnsv4W1wixpFDvACwAAlkLCi",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Shopify",
  "alias": "shopify",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T23:54:33.411Z",
  "url": "https://events.hookdeck.com/e/src_cnsv4W1wixpFDvACwAAlkLCi"
}

Destinations

The Destination object is used to define where your webhook events will be sent.

Endpoints

GET
https://api.hookdeck.com/destinations

GET
https://api.hookdeck.com/destinations/:id

POST
https://api.hookdeck.com/destinations

PUT
https://api.hookdeck.com/destinations

PUT
https://api.hookdeck.com/destinations/:id

PUT
https://api.hookdeck.com/destinations/:id/archive

PUT
https://api.hookdeck.com/destinations/:id/unarchive

Destination object

Parameter Type Default Description
id string ID of the destination
team_id string ID of the workspace
label string Name of the destination
alias string A unique, human friendly id for the destination
url url HTTP Endpoint of the destination
cli_path string Path for the CLI destination
rate_limit number Limit event attempts to receive per period. Max 100/second or 6000/minute
rate_limit_period string 'second' Period to rate limit attempts. (second or minute)
archived_at ISO Date null Date the destination was archived
updated_at ISO Date Last ISO Date the destination was updated
created_at ISO Date Date the destination was created 
{
  "id": "des_5b3mzbxk83dciim",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "cli_path": "/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second",
  "archived_at": null,
  "updated_at": "2020-03-26T17:15:31.079Z",
  "created_at": "2020-03-22T18:22:38.015Z"
}

Retrieve all destinations

Query Parameter

Parameter Type Description
id string[] Filter by destination ids
alias string The destination alias
archived boolean Include the archived resources in response
archived_at date Date the destination was archived
url string HTTP Endpoint of the destination
cli_path string Path for the CLI destination
limit number Limit the returned event count. Max 250.
GET
https://api.hookdeck.com/destinations

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "des_1hg4DlAaBTTigG8oWU4lLmpu"
  },
  "count": 1,
  "models": [
    {
      "id": "des_1hg4DlAaBTTigG8oWU4lLmpu",
      "team_id": "tm_2wx4z178zk82c4hh9",
      "label": "My API",
      "alias": "my-api",
      "url": "https://example.com/webhook",
      "cli_path": "/webhook",
      "rate_limit": 5,
      "rate_limit_period": "second",
      "archived_at": null,
      "updated_at": "2021-01-21T23:53:41.732Z",
      "created_at": "2021-01-21T23:53:41.706Z"
    }
  ]
}

Retrieve a destination

URL Parameter

Parameter Description
id Destination ID
GET
https://api.hookdeck.com/destinations/:id

Response Example

{
  "id": "des_oVC3AC3Lo97HlpADYFvyJsCJ",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "cli_path": "/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second",
  "archived_at": "2021-01-21T23:53:41.737Z",
  "updated_at": "2021-01-21T23:53:41.738Z",
  "created_at": "2021-01-21T22:49:43.604Z"
}

Create a destination

This endpoint creates a destination. One of url or cli_path is mandatory

Body Parameters

Parameter Type Description
label string Name of the destination
alias string Alternate name for the destination
url url Endpoint of the destination
cli_path string Path for the CLI destination
rate_limit number Limit event attempts to receive per period. Max 100/second or 6000/minute
rate_limit_period string Period to rate limit attempts. (second or minute)
POST
https://api.hookdeck.com/destinations

Request Body

{
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second"
}

Response Example

{
  "id": "des_oVC3AC3Lo97HlpADYFvyJsCJ",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "cli_path": null,
  "rate_limit": 5,
  "rate_limit_period": "second",
  "archived_at": "2021-01-21T23:54:33.443Z",
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T22:49:43.604Z"
}

Create/Update a destination

This endpoint creates a destination or updates an existing destination by alias.

Body Parameters

Parameter Type Description
label string Name of the destination
alias string Alternate name for the destination
url url Endpoint of the destination
rate_limit number Limit event attempts to receive per period. Max 100/second or 6000/minute
rate_limit_period string Period to rate limit attempts. (second or minute)
PUT
https://api.hookdeck.com/destinations

Request Body

{
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second"
}

Response Example

{
  "id": "des_oVC3AC3Lo97HlpADYFvyJsCJ",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second",
  "archived_at": "2021-01-21T23:54:33.443Z",
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T22:49:43.604Z"
}

Update a destination

This endpoint updates a destination.

URL Parameter

Parameter Description
id Destination ID

Body Parameters

Parameter Type Description
label string Name of the destination
alias string Alternate name for the destination
url url Endpoint of the destination
cli_path string Path for the CLI destination
rate_limit number Limit event attempts to receive per period. Max 100/second or 6000/minute
rate_limit_period string Period to rate limit attempts. (second or minute)
PUT
https://api.hookdeck.com/destinations/:id

Request Body

{
  "label": "My New API"
}

Response Example

{
  "id": "des_oVC3AC3Lo97HlpADYFvyJsCJ",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "cli_path": null,
  "rate_limit": 5,
  "rate_limit_period": "second",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.442Z",
  "created_at": "2021-01-21T22:49:43.604Z"
}

Archive a destination

This endpoint archives a destination.

URL Parameter

Parameter Description
id Destination ID
PUT
https://api.hookdeck.com/destinations/:id/archive

Response Example

{
  "id": "des_oVC3AC3Lo97HlpADYFvyJsCJ",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "cli_path": "/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second",
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T22:49:43.604Z"
}

Unarchive a destination

URL Parameter

Parameter Description
id Destination ID
PUT
https://api.hookdeck.com/destinations/:id/unarchive

Response Example

{
  "id": "des_oVC3AC3Lo97HlpADYFvyJsCJ",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "My API",
  "alias": "my-api",
  "url": "https://example.com/webhook",
  "cli_path": "/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second",
  "archived_at": "2021-01-21T23:54:33.443Z",
  "updated_at": "2021-01-21T23:54:33.443Z",
  "created_at": "2021-01-21T22:49:43.604Z"
}

Rulesets

The Ruleset object is used to define the retry and alert logic of your webhook connection.

Endpoints

GET
https://api.hookdeck.com/rulesets

GET
https://api.hookdeck.com/rulesets/:id

POST
https://api.hookdeck.com/rulesets

PUT
https://api.hookdeck.com/rulesets

PUT
https://api.hookdeck.com/rulesets/:id

PUT
https://api.hookdeck.com/rulesets/:id/archive

PUT
https://api.hookdeck.com/rulesets/:id/unarchive

Ruleset object

Parameter Type Default Description
id string ID of the ruleset
team_id string ID of the workspace
label string Name of the ruleset
alias string null A unique, human friendly id for the ruleset
retry_count integer 5 Number of retry attempts
retry_interval integer 3600000 Time interval between retries in ms
retry_strategy string "linear" Algorithm to apply to the retry interval. One of linear or exponential
alert_interval integer 3600000 Time interval between alerts in ms
alert_strategy string last_attempt Alert strategy for the ruleset. One of last_attempt or each_attempt
is_team_default boolean true Default ruleset of Workspace
archived_at date null Date the ruleset was archived
updated_at date Last ISO Date the ruleset was updated
created_at date Date the ruleset was created 
{
  "id": "rls_5b3mzbxk83c0k89",
  "alias": "default-ruleset",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "label": "Default Ruleset",
  "retry_count": 5,
  "retry_interval": 3600000,
  "retry_strategy": "linear",
  "is_team_default": true,
  "archived_at": null,
  "updated_at": "2020-03-22T17:45:20.742Z",
  "created_at": "2020-03-22T17:45:20.746Z",
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt"
}

Retrieve all rulesets

Query Parameter

Parameter Type Description
id string[] Filter by ruleset ids
alias string The ruleset alias
archived boolean Include the archived resources in response
archived_at date Date the ruleset was archived
limit number Limit the returned event count. Max 250.
GET
https://api.hookdeck.com/rulesets

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "rls_M5dzwXYgibJllEeA8t05AhbH"
  },
  "count": 1,
  "models": [
    {
      "id": "rls_M5dzwXYgibJllEeA8t05AhbH",
      "alias": "fast-retry-ruleset",
      "team_id": "tm_2wx4z178zk82c4hh9",
      "label": "Fast Retry Ruleset",
      "retry_count": 10,
      "retry_interval": 60000,
      "retry_strategy": "linear",
      "is_team_default": false,
      "archived_at": null,
      "updated_at": "2021-01-21T23:53:41.735Z",
      "created_at": "2021-01-21T23:53:41.706Z",
      "alert_interval": 3600000,
      "alert_strategy": "last_attempt"
    }
  ]
}

Retrieve a ruleset

URL Parameter

Parameter Description
id Ruleset ID
GET
https://api.hookdeck.com/rulesets/:id

Response Example

{
  "id": "rls_jQjYXrgekBIRbvi2U2aFz6wf",
  "alias": "fast-retry-ruleset",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Fast Retry Ruleset",
  "retry_count": 10,
  "retry_interval": 120000,
  "retry_strategy": "linear",
  "is_team_default": false,
  "archived_at": "2021-01-21T23:53:41.755Z",
  "updated_at": "2021-01-21T23:53:41.755Z",
  "created_at": "2021-01-21T23:11:07.995Z",
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt"
}

Create a ruleset

This endpoint creates a ruleset.

Body Parameters

Parameter Type Description
alias string Alternate name for the ruleset
label string Name of the ruleset
retry_count integer Number of retry attempts
retry_interval integer Time interval between retries in ms. Min 60000
alert interval integer Time interval between alerts in ms
alert strategy string Alert strategy for the ruleset (null, each_attempt or last_attempt)
POST
https://api.hookdeck.com/rulesets

Request Body

{
  "label": "Fast Retry Ruleset",
  "alias": "fast-retry-ruleset",
  "retry_count": 10,
  "retry_interval": 60000,
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt"
}

Response Example

{
  "id": "rls_NcH29zS3gnY0z7vWlAnexosp",
  "label": "Fast Retry Ruleset",
  "retry_count": 10,
  "retry_interval": 60000,
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "alias": "fast-retry-ruleset",
  "created_at": "2021-01-21T23:54:33.411Z",
  "retry_strategy": "linear",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.444Z"
}

Create/Update a ruleset

This endpoint creates a ruleset or updates an existing ruleset by alias.

Body Parameters

Parameter Type Description
alias string Alternate name for the ruleset
label string Name of the ruleset
retry_count integer Number of retry attempts
retry_interval integer Time interval between retries in ms. Min 60000
alert interval integer Time interval between alerts in ms
alert strategy string Alert strategy for the ruleset (null, each_attempt or last_attempt)
PUT
https://api.hookdeck.com/rulesets

Request Body

{
  "label": "Fast Retry Ruleset",
  "alias": "fast-retry-ruleset",
  "retry_count": 10,
  "retry_interval": 60000,
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt"
}

Response Example

{
  "id": "rls_NcH29zS3gnY0z7vWlAnexosp",
  "label": "Fast Retry Ruleset",
  "retry_count": 10,
  "retry_interval": 60000,
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "alias": "fast-retry-ruleset",
  "created_at": "2021-01-21T23:54:33.411Z",
  "retry_strategy": "linear",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.444Z"
}

Update a ruleset

This endpoint updates a ruleset.

URL Parameter

Parameter Description
id Ruleset ID

Body Parameters

Parameter Type Description
alias string Alternate name for the ruleset
label string Name of the ruleset
retry_count integer Number of retry attempts
retry_interval integer Time interval between retries in ms. Min 60000
alert interval integer Time interval between alerts in ms
alert strategy string Alert strategy for the ruleset (null, each_attempt or last_attempt)
PUT
https://api.hookdeck.com/rulesets/:id

Request Body

{
  "retry_interval": 120000
}

Response Example

{
  "id": "rls_jQjYXrgekBIRbvi2U2aFz6wf",
  "alias": "fast-retry-ruleset",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Fast Retry Ruleset",
  "retry_count": 10,
  "retry_interval": 120000,
  "retry_strategy": "linear",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.419Z",
  "created_at": "2021-01-21T23:11:07.995Z",
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt"
}

Archive a ruleset

This endpoint archives a ruleset.

URL Parameter

Parameter Description
id Ruleset ID
PUT
https://api.hookdeck.com/rulesets/:id/archive

Response Example

{
  "id": "rls_jQjYXrgekBIRbvi2U2aFz6wf",
  "alias": "fast-retry-ruleset",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Fast Retry Ruleset",
  "retry_count": 10,
  "retry_interval": 120000,
  "retry_strategy": "linear",
  "is_team_default": false,
  "archived_at": "2021-01-21T23:54:33.461Z",
  "updated_at": "2021-01-21T23:54:33.461Z",
  "created_at": "2021-01-21T23:11:07.995Z",
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt"
}

Unarchive a ruleset

URL Parameter

Parameter Description
id Ruleset ID
PUT
https://api.hookdeck.com/rulesets/:id/unarchive

Response Example

{
  "id": "rls_jQjYXrgekBIRbvi2U2aFz6wf",
  "alias": "fast-retry-ruleset",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "label": "Fast Retry Ruleset",
  "retry_count": 10,
  "retry_interval": 120000,
  "retry_strategy": "linear",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-01-21T23:54:33.461Z",
  "created_at": "2021-01-21T23:11:07.995Z",
  "alert_interval": 3600000,
  "alert_strategy": "last_attempt"
}

Events

An event represents a webhook that's been received by Hookdeck.

Endpoints

GET
https://api.hookdeck.com/events

GET
https://api.hookdeck.com/events/:id

POST
https://api.hookdeck.com/events/:id/retry

PUT
https://api.hookdeck.com/events/:id/mute

Event object

Parameter Type Default Description
id string ID of the event
team_id string ID of the workspace
webhook_id string ID of the associated connection
source_id string ID of the associated source
destination_id string ID of the associated destination
cli_id string null ID of the CLI the event is sent to
event_request_id string ID of the request data
attempts number 0 Number of delivery attempts made
status string null Lifecyle status of the event. One of QUEUED, HOLD, SUCCESSFUL, FAILED
response_status number null Event status
error_code string null None HTTP error code.
last_attempt_at date null Last date a retry was attempted
next_attempt_at date null Next date of a scheduled retry
sucessful_at date null date of the latest successful attempt
updated_at date Last date the event was updated
created_at date Date the event was created 
{
  "id": "evt_5b3mzbxk83deakr",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "webhook_id": "web_5b3mzbxk83dcij0",
  "source_id": "src_5b3mzbxk83dciin",
  "destination_id": "des_5b3mzbxk83dciim",
  "cli_id": null,
  "event_request_id": "evtreq_Ixux8vb2VBnZIuieVFPcUF9d",
  "attempts": 0,
  "status": "QUEUED",
  "response_status": null,
  "last_attempt_at": null,
  "next_attempt_at": null,
  "successful_at": null,
  "updated_at": "2020-03-22T18:24:01.031Z",
  "created_at": "2020-03-22T18:24:01.035Z"
}

Retrieve all events

List all events or a subset of events.

Filtering retrieved events

Query Parameter

Parameter Type Description
id string[] Filter by event ids
webhook_id string[] Filter by webhook connection ids
source_id string[] Filter by source ids
destination_id string[] Filter by destination ids
cli_id string[] Filter by cli ids. ?[any]=true operator for any CLI. Defaults to null
status string null Lifecyle status of the event. One of QUEUED, HOLD, SUCCESSFUL, FAILED
response_status number Filter by HTTP response status code
attempts number Filter by number of attempts
created_at date Filter by created_at date using a date
successful_at date Filter by last_attempt_at date using a date
last_attempt_at date Filter by last_attempt_at date using a date
next_attempt_at date Filter by next_attempt_at date using a date
body JSON URL Encoded string of the JSON to match to the request body
headers JSON URL Encoded string of the JSON to match to the request headers
parsed_query JSON URL Encoded string of the JSON to match to the parsed query (JSON representation of the query)
path string URL Encoded string of the string to match partially to the path
limit string Limit the returned event count. Max 250.
order_by string Sort by created_at (default) or last_attempt_at.
GET
https://api.hookdeck.com/events

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "evt_YxIoOb1bvnXoPFmWQZ94a8A8"
  },
  "count": 1,
  "models": [
    {
      "id": "evt_YxIoOb1bvnXoPFmWQZ94a8A8",
      "team_id": "tm_2wx4z178zk82c4hh9",
      "webhook_id": "web_N5rXux0ggNw8L64MGIYZOMqL",
      "source_id": "src_idW85YkZsTjqq1hce1UW4BL8",
      "destination_id": "des_cYVgCxVAjrYYGPDHvN6GV4IU",
      "attempts": 12,
      "response_status": null,
      "last_attempt_at": "2021-01-21T23:53:41.802Z",
      "next_attempt_at": null,
      "successful_at": "2021-01-07T01:45:06.501Z",
      "updated_at": "2021-01-21T23:53:41.830Z",
      "created_at": "2021-01-07T01:44:56.399Z",
      "status": "FAILED",
      "cli_id": null,
      "event_request_id": "evtreq_kjX4qRCyoX4hsaDRSvXI20nl"
    }
  ]
}

Retrieve an event

When retrieving a specific event, the response will contain the request object with the properties body and headers. The original data for that webhook request.

URL Parameter

Parameter Description
id Event ID
GET
https://api.hookdeck.com/events/:id

Response Example

{
  "id": "evt_YxIoOb1bvnXoPFmWQZ94a8A8",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "webhook_id": "web_N5rXux0ggNw8L64MGIYZOMqL",
  "source_id": "src_idW85YkZsTjqq1hce1UW4BL8",
  "destination_id": "des_cYVgCxVAjrYYGPDHvN6GV4IU",
  "attempts": 12,
  "response_status": null,
  "last_attempt_at": "2021-01-21T23:53:41.802Z",
  "next_attempt_at": null,
  "successful_at": "2021-01-07T01:45:06.501Z",
  "updated_at": "2021-01-21T23:53:41.830Z",
  "created_at": "2021-01-07T01:44:56.399Z",
  "status": "SUCCESSFUL",
  "cli_id": null,
  "event_request_id": "evtreq_kjX4qRCyoX4hsaDRSvXI20nl",
  "request": {
    "headers": {
      "test": "true",
      "time": "12",
      "user-agent": "PostmanRuntime/7.26.8",
      "content-type": "application/x-www-form-urlencoded",
      "content-length": "25",
      "x-original-url": "/e/src_idW85YkZsTjqq1hce1UW4BL8"
    },
    "body": {
      "test": "{test: true}"
    }
  }
}

Retry an event

This endpoint manually queues an event for retry.

URL Parameter

Parameter Description
id Event ID
POST
https://api.hookdeck.com/events/:id/retry

Response Example

{
  "id": "atm_bY3R57X7YSJ81UJcDpLmam5X",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "event_id": "evt_YxIoOb1bvnXoPFmWQZ94a8A8",
  "response_status": null,
  "successful_at": null,
  "updated_at": "2021-01-21T23:54:33.522Z",
  "created_at": "2021-01-21T23:54:33.507Z",
  "error_code": "CONNECTION_REFUSED",
  "body": {}
}

Mute an event

This endpoint cancels the next automatic retry.

URL Parameter

Parameter Description
id Event ID
PUT
https://api.hookdeck.com/events/:id/mute

Response Example

{
  "id": "evt_YxIoOb1bvnXoPFmWQZ94a8A8",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "webhook_id": "web_N5rXux0ggNw8L64MGIYZOMqL",
  "source_id": "src_idW85YkZsTjqq1hce1UW4BL8",
  "destination_id": "des_cYVgCxVAjrYYGPDHvN6GV4IU",
  "attempts": 12,
  "response_status": null,
  "last_attempt_at": "2021-01-21T23:53:41.802Z",
  "next_attempt_at": null,
  "successful_at": "2021-01-07T01:45:06.501Z",
  "updated_at": "2021-01-21T23:54:33.387Z",
  "created_at": "2021-01-07T01:44:56.399Z",
  "status": "SUCCESSFUL",
  "event_request_id": "evtreq_kjX4qRCyoX4hsaDRSvXI20nl",
  "cli_id": null,
  "request": {
    "headers": {
      "test": "true",
      "time": "12",
      "user-agent": "PostmanRuntime/7.26.8",
      "content-type": "application/x-www-form-urlencoded",
      "content-length": "25",
      "x-original-url": "/e/src_idW85YkZsTjqq1hce1UW4BL8"
    },
    "body": {
      "test": "{test: true}"
    }
  }
}

Attempts

The Attempt object allows you to monitor the attempts of your events.

Endpoints

GET
https://api.hookdeck.com/attempts

GET
https://api.hookdeck.com/attempts/:id

GET
https://api.hookdeck.com/attempts

GET
https://api.hookdeck.com/attempts/:id

Attempt object

Parameter Type Default Description
id string Attempt ID
team_id string Deck ID
event_id string Event ID
error_code string Attempt could not complete because of an error
sucessful_at ISO Date null Date of the successful event
updated_at ISO Date Last ISO Date the event was updated
created_at ISO Date Date the event was created 
{
  "id": "atm_12n4ffxk8adnqqj",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "event_id": "evt_12n4ffxk8admulc",
  "response_status": 500,
  "successful_at": null,
  "updated_at": "2020-03-27T16:05:45.240Z",
  "created_at": "2020-03-27T16:05:45.115Z"
}

Retrieve all attempts

Query Parameter

Parameter Type Description
event_id string[] Event the attempt is associated with
GET
https://api.hookdeck.com/attempts

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "atm_M39yPpyXITxZ7SjBF8cpHIGP"
  },
  "count": 1,
  "models": [
    {
      "id": "atm_M39yPpyXITxZ7SjBF8cpHIGP",
      "team_id": "tm_2wx4z178zk82c4hh9",
      "event_id": "evt_YxIoOb1bvnXoPFmWQZ94a8A8",
      "response_status": null,
      "successful_at": null,
      "updated_at": "2021-01-21T23:53:41.819Z",
      "created_at": "2021-01-21T23:53:41.802Z",
      "error_code": "CONNECTION_REFUSED"
    }
  ]
}

Retrieve an attempt

When retrieving a specific attempt the response will contain the body of the request's response if the request has been completed.

URL Parameter

Parameter Description
id Attempt ID
GET
https://api.hookdeck.com/attempts/:id

Response Example

{
  "id": "atm_7zlEBoR7SIdt864UvGw8ufNp",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "event_id": "evt_2ON3uY0F9edDpbsuuub7LnKB",
  "response_status": null,
  "successful_at": null,
  "updated_at": "2021-01-09T05:15:44.559Z",
  "created_at": "2021-01-09T05:15:44.537Z",
  "error_code": "CONNECTION_REFUSED",
  "body": {}
}

Bulk

A bulk request allows you to perform actions on multiple objects at once.

Endpoints

POST
https://api.hookdeck.com/bulk/events/retry

Retry events

This endpoint retries events in bulk matching a query.

Body Parameters

Parameter Type Default Description
dry_run boolean true Returns events to be retried by the query without retrying
id string[] Filter by event ids
webhook_id string[] Filter by webhook connection ids
source_id string[] Filter by source ids
destination_id string[] Filter by destination ids
response_status number Filter by response status
attempts number Filter by number of attempts
created_at date Filter by created_at date using a date
successful_at date Filter by last_attempt_at date using a date
last_attempt_at date Filter by last_attempt_at date using a date
next_attempt_at date Filter by next_attempt_at date using a date
body JSON JSON to match to the request body
headers JSON JSON to match to the request headers
parsed_query JSON JSON to match to the parsed query (JSON representation of the query)
path string String to match partially to the path
limit string Limit the returned event count. Max 250.
dir string desc The direction to sort it ("asc" or "desc")
order_by string created_at Sort by created_at (default) or last_attempt_at.
next string The ID to provide in the query to get the next set of results
prev string The ID to provide in the query to get the previous set of results
POST
https://api.hookdeck.com/bulk/events/retry

Request Body

{
  "dry_run": false,
  "limit": 2,
  "headers": {
    "user-agent": "PostmanRuntime/7.26.8"
  }
}

Response Example

{
  "id": "blkret_xGgwC8cFXZ2TdBmnR5eepv51",
  "team_id": "tm_2wx4z178zk82c4hh9",
  "query": {
    "headers": "{\"user-agent\":\"PostmanRuntime/7.26.8\"}",
    "order_by": "created_at",
    "dir": "desc",
    "limit": 2
  },
  "updated_at": "2021-02-01T04:46:42.273Z",
  "created_at": "2021-02-01T04:46:42.271Z",
  "processed": [
    "evt_YxIoOb1bvnXoPFmWQZ94a8A8",
    "evt_2ON3uY0F9edDpbsuuub7LnKB"
  ],
  "unprocessed": [],
  "next": "evt_2ON3uY0F9edDpbsuuub7LnKB"
}

Bookmarks

A bookmark represents a save event request to play replayed or tested against.

Endpoints

GET
https://api.hookdeck.com/bookmarks

GET
https://api.hookdeck.com/bookmarks/:id

POST
https://api.hookdeck.com/bookmarks

PUT
https://api.hookdeck.com/bookmarks/:id

PUT
https://api.hookdeck.com/bookmarks/:id/trigger

DELETE
https://api.hookdeck.com/bookmarks/:id

Bookmark object

Parameter Type Default Description
id string ID of the bookmark
team_id string ID of the workspace
label string Descriptive name of the bookmark
alias string A unique, human friendly id for the bookmark
webhook_id string ID of the associated connection
event_request_id string ID of the bookmarked event request
last_used_at ISO Date null Last ISO Date the bookmark was manually triggered
updated_at ISO Date Last ISO Date the bookmark was updated
created_at ISO Date Date the bookmark was created 
{
  "id": "bmk_zRQrmyGVDOEpPcwPqWjeI0p4",
  "team_id": "tm_yUEO9119dsca8EgUE6qwXdCM",
  "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q",
  "label": "Product Update – Out of Stock",
  "alias": null,
  "event_request_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
  "last_used_at": "2021-04-29T03:46:32.390Z",
  "updated_at": "2021-04-29T03:46:32.394Z",
  "created_at": "2021-04-25T00:39:04.232Z",
  "request": {
    "headers": {
      "content-type": "text/plain",
      "content-length": "20"
    },
    "body": {
      "example": true
    }
  }
}

Retrieve all bookmarks

Query Parameter

Parameter Type Description
id string Filter by bookmark ids
alias string Filter by bookmark alias
webhook_id string Filter by associated connection ID
event_request_id string Filter by associated event request ID
label string Filter by label
last_used_at Date Filter by last used date
limit number Limit the returned event count. Max 250.
GET
https://api.hookdeck.com/bookmarks

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100
  },
  "count": 1,
  "models": [
    {
      "id": "bmk_zRQrmyGVDOEpPcwPqWjeI0p4",
      "team_id": "tm_yUEO9119dsca8EgUE6qwXdCM",
      "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q",
      "label": "Product Update – Out of Stock",
      "alias": null,
      "event_request_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
      "last_used_at": "2021-04-29T03:46:32.390Z",
      "updated_at": "2021-04-29T03:46:32.394Z",
      "created_at": "2021-04-25T00:39:04.232Z"
    }
  ]
}

Retrieve a bookmark

URL Parameter

Parameter Description
id Bookmark ID
GET
https://api.hookdeck.com/bookmarks/:id

Response Example

{
  "id": "bmk_zRQrmyGVDOEpPcwPqWjeI0p4",
  "team_id": "tm_yUEO9119dsca8EgUE6qwXdCM",
  "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q",
  "label": "Product Update – Out of Stock",
  "alias": null,
  "event_request_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
  "last_used_at": "2021-04-29T03:46:32.390Z",
  "updated_at": "2021-04-29T03:46:32.394Z",
  "created_at": "2021-04-25T00:39:04.232Z",
  "request": {
    "headers": {
      "content-type": "application/json",
      "content-length": "20"
    },
    "body": {
      "example": true
    }
  }
}

Create a bookmark

Body Parameters

Parameter Type Description
label string Name of the bookmark
alias string [Optional] Alternate name for the bookmark
webhook_id string ID of the associated connection
event_request_id string ID of the event request to bookmark
POST
https://api.hookdeck.com/bookmarks

Request Body

{
  "label": "Product Update – Out of Stock",
  "event_request_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
  "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q"
}

Response Example

{
  "id": "bmk_zRQrmyGVDOEpPcwPqWjeI0p4",
  "team_id": "tm_yUEO9119dsca8EgUE6qwXdCM",
  "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q",
  "label": "Product Update – Out of Stock",
  "alias": null,
  "event_request_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
  "last_used_at": "2021-04-29T03:46:32.390Z",
  "updated_at": "2021-04-29T03:46:32.394Z",
  "created_at": "2021-04-25T00:39:04.232Z",
  "request": {
    "headers": {
      "content-type": "application/json",
      "content-length": "20"
    },
    "body": {
      "example": true
    }
  }
}

Update a bookmark

This endpoint updates a bookmark.

URL Parameter

Parameter Description
id Bookmark ID

Body Parameters

Parameter Type Description
label string Name of the bookmark
alias string [Optional] Alternate name for the bookmark
webhook_id string ID of the associated connection
event_request_id string ID of the event request to bookmark
PUT
https://api.hookdeck.com/bookmarks/:id

Request Body

{
  "label": "Product Update – Out of Stock",
  "event_request_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
  "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q"
}

Response Example

{
  "id": "bmk_zRQrmyGVDOEpPcwPqWjeI0p4",
  "team_id": "tm_yUEO9119dsca8EgUE6qwXdCM",
  "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q",
  "label": "Product Update – Out of Stock",
  "alias": null,
  "event_request_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
  "last_used_at": "2021-04-29T03:46:32.390Z",
  "updated_at": "2021-04-29T03:46:32.394Z",
  "created_at": "2021-04-25T00:39:04.232Z",
  "request": {
    "headers": {
      "content-type": "application/json",
      "content-length": "20"
    },
    "body": {
      "example": true
    }
  }
}

Trigger a bookmark

Trigger a bookmark to create events. Many events could be created depending on the target. There will be at most 1 event for HTTP bookmarks and as many events as there are CLI clients listening to the associated connection.

URL Parameter

Parameter Description
id Bookmark ID

Body Parameters

Parameter Type Description
target string [Optional] cli or http
POST
https://api.hookdeck.com/bookmarks/:id/trigger

Response Example

[
  {
    "id": "evt_8ezP8R4BYnHs2asHSgJuGuXr",
    "team_id": "tm_yUEO9119dsca8EgUE6qwXdCM",
    "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q",
    "source_id": "src_R7XYDpbMmZ4fU709BvvWT4fj",
    "destination_id": "des_yDcdnetDYbO6O4MXZijVoThT",
    "attempts": 0,
    "response_status": null,
    "last_attempt_at": null,
    "next_attempt_at": null,
    "successful_at": null,
    "updated_at": "2021-04-30T15:40:33.811Z",
    "created_at": "2021-04-30T15:40:33.812Z",
    "status": "QUEUED",
    "event_request_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
    "cli_id": null,
    "request": {
      "headers": {
        "content-type": "application/json",
        "content-length": "20"
      },
      "body": {
        "example": true
      }
    }
  }
]

Delete a bookmark

Deleting a bookmark won't affect the triggered events.

URL Parameter

Parameter Description
id Bookmark ID
DELETE
https://api.hookdeck.com/bookmarks/:id

Response Example

"bmk_zRQrmyGVDOEpPcwPqWjeI0p4"

Get In Touch

Hookdeck team has a Spectrum community where you can chat with the makers @Alexandre Bouchard & @Eric Tran and other users. We will answer your questions, help you get set up, and listen and respond to all your ideas & complaints!

You can also contact the Hookdeck team by email at [email protected]!