API Reference - Hookdeck

Introduction

Getting Started Paging Errors Query Formating

Resources

Webhook Connections Sources Destinations Rulesets Events Attempts Bulk

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

You must replace BASE64_API_TOKEN with your personal API key.

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.

The API currently only supports application/json for both input and output. Header is optional.

POST

https://api.hookdeck.com/connections

Request Body

{
  "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",
  "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.

Connections historically were labeled "webhooks". The endpoint root path /webhooks has been moved to /connections. The former will remain functional but consider migrating to /connections

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
ruletset	`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

Example Webhook Connection

{
  "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",
      "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",
  "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
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

{
  "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",
  "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

{
  "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
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

{
  "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",
  "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
ruletset	`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",
  "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

The parameter archived_at is set to the current timestamp.

PUT

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

Response Example

{
  "id": "web_te6bgdS4X6i5f5xcczTYDwey",
  "label": "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

The parameter archived_at is set to null

PUT

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

Response Example

{
  "id": "web_te6bgdS4X6i5f5xcczTYDwey",
  "label": "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'.

Example Source

{
  "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

The parameter archived_at is set to the current timestamp.

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

The parameter archived_at is set to null

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

Example Destination

{
  "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

The parameter archived_at is set to the current timestamp.

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

The parameter archived_at is set to null

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"`	Apply linear between interval retries
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

Example Ruleset

{
  "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

The parameter archived_at is set to the current timestamp.

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

The parameter archived_at is set to null

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
response_status	`number`	`null`	Event status
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

Example Event

{
  "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,
  "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

Retrieve all failed events

/events?response_status[gte]=300

Retrieve all successful event

/events?response_status[lt]=300

Retrieve events between two dates

/events?created_at[gte]=2020-10-01&created_at[lte]=2020-10-16

Retrieve events excluding cli events

/events?cli_id=

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
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
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": "NONE",
      "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": "NONE",
  "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

Automatic retries are cancelled. The parameter next_attempt_at is set to null. This action is NOT reversible.

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": "NONE",
  "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

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

Example Attempt

{
  "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
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"
}

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]!