API Reference - Hookdeck

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.

Hookdeck API was historically available on api.hookdeck.io and has been moved to api.hookdeck.com. The former will remain functional but consider migrating to api.hookdeck.com.

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/2021-08-01/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
name	`string`	Name of the webhook

Source

Parameter	Type	Description
name	`string`	Name of the source

Destination

One of url or cli_path is mandatory

Parameter	Type	Description
name	`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 /2021-08-01/connections

Request Body

{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "url": "https://example.com/webhook"
  }
}

Response Example

{
  "id": "web_3tVBgTFuuzmEnsWa9eBywz6j",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.575Z",
  "created_at": "2021-08-02T14:12:56.611Z",
  "paused_at": null,
  "name": "shopify-my-api",
  "rules": [],
  "destination": {
    "id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://example.com/webhook",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.591Z",
    "created_at": "2021-08-02T14:12:56.589Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": null,
    "path_forwarding_disabled": false,
    "name": "my-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.586Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2021-08-02T13:52:16.888Z",
    "created_at": "2021-08-01T21:29:36.367Z",
    "name": "default-ruleset",
    "rules": [
      {
        "type": "retry",
        "count": 5,
        "interval": 10800000,
        "strategy": "linear"
      },
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    },
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

Example reusing a resource

{
  "name": "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 source object

{
  "id": "web_xxxxxxxxxxxxxxx",
  "source": {
    "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.

If an event is pending, the keyset will return a truthy value (null) which will cause the pagination to omit null values in the response.

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.hookdeck.com/2021-08-01/connections?next=web_2urj7h9puxk6obro3x"
  -H "Authorization: Basic BASE64_API_TOKEN"

Example to get the previous page:

curl "https://api.hookdeck.com/2021-08-01/connections?previous=web_2urj7h9puxk6obuf6i"
  -H "Authorization: Basic BASE64_API_TOKEN"

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

curl "https://api.hookdeck.com/2021-08-01/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.hookdeck.com/2021-08-01/connections?next=web_2urj7h9puxk6obro3x"
  -H "Authorization: Basic BASE64_API_TOKEN"

Example to get the previous page:

curl "https://api.hookdeck.com/2021-08-01/connections?previous=web_2urj7h9puxk6obuf6i"
  -H "Authorization: Basic BASE64_API_TOKEN"

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

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

Changelog

When backwards-incompatible changes are made to the API, a new, dated version is released. The latest version is, 2021-08-01.

The API version can be set in the base path of any endpoint such as https://api.hookdeck.com/2021-08-01/sources.

If your request doesn't include a version, then the API also defaults to the oldest supported stable version.

The backward incompatible changes are listed bellow for each version. Forward-compatible changes don’t need a new API version and will not appear in this list.

2021-08-01

Removed the label property for Sources, Destinations, Rulesets and Connections.
Renamed the alias property to name for Sources, Destinations, Ruleset and Connections.
Removed the alert_strategy and alert_interval property for Rulesets.
Removed the retry_strategy, retry_interval and retry_count property for Rulesets.
Removed the filters property for Connections.
Add the rules property to Connections and Rulesets.

Introducing Rules

The removed properties of Rulesets and Connections have been replaced by the rules array. Each rules has a type and a set of property to configure it's behavior. Rules definitions are found here

2020-01-01

2020-01-01 marks the intial released of the API.

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 /2021-08-01/connections
GET /2021-08-01/connections/:id
POST /2021-08-01/connections
PUT /2021-08-01/connections
PUT /2021-08-01/connections/:id
PUT /2021-08-01/connections/:id/archive
PUT /2021-08-01/connections/:id/unarchive
PUT /2021-08-01/connections/:id/pause
PUT /2021-08-01/connections/:id/unpause

Webhook Connection object

Parameter	Type	Default	Description
id	`string`		ID of the connection
name	`string`		Unique name of the connection for this 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
resolved_rules	`Rule[]`	`[]`	Array of rules applied to connection after factoring for the ruleset
rules	`Rule[]`	`[]`	Array of rules configured on the connection

{
  "id": "web_mNP60lEYInVfnH1EUWbhfUYL",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T00:26:46.620Z",
  "created_at": "2021-08-02T00:26:47.070Z",
  "paused_at": null,
  "name": "shopify-my-api",
  "rules": [],
  "destination": {
    "id": "des_6MO6QjY7pOotcDaFZfw2hoWF",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://example.com/webhook",
    "archived_at": null,
    "updated_at": "2021-08-02T00:26:46.827Z",
    "created_at": "2021-08-02T00:25:31.858Z",
    "rate_limit": 5,
    "rate_limit_period": "second",
    "cli_path": null,
    "path_forwarding_disabled": false,
    "name": "my-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T00:26:46.816Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2021-08-02T00:26:46.649Z",
    "created_at": "2021-08-01T21:29:36.367Z",
    "name": "default-ruleset",
    "rules": [
      {
        "type": "retry",
        "count": 5,
        "interval": 10800000,
        "strategy": "linear"
      },
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    },
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

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 /2021-08-01/connections

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "web_szbJuSoCxatxFytJdqdsfGHL"
  },
  "count": 1,
  "models": [
    {
      "id": "web_szbJuSoCxatxFytJdqdsfGHL",
      "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
      "archived_at": null,
      "updated_at": "2021-08-02T14:10:47.407Z",
      "created_at": "2021-08-02T14:09:56.133Z",
      "paused_at": null,
      "name": "example-destination",
      "rules": [],
      "destination": {
        "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
        "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
        "url": "https://mock.hookdeck.com",
        "archived_at": null,
        "updated_at": "2021-08-02T14:09:56.117Z",
        "created_at": "2021-08-02T14:09:56.116Z",
        "rate_limit": null,
        "rate_limit_period": "second",
        "cli_path": "/",
        "path_forwarding_disabled": false,
        "name": "example-destination"
      },
      "ruleset": {
        "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
        "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
        "is_team_default": false,
        "archived_at": null,
        "updated_at": "2021-08-02T14:10:47.400Z",
        "created_at": "2021-08-02T14:10:47.399Z",
        "name": "example-ruleset",
        "rules": [
          {
            "type": "alert",
            "interval": 86400000,
            "strategy": "last_attempt"
          }
        ]
      },
      "source": {
        "id": "src_2Q0cNXCHyzPJCUOmpk76JKeU",
        "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
        "archived_at": null,
        "updated_at": "2021-08-01T21:48:16.865Z",
        "created_at": "2021-08-01T21:45:07.100Z",
        "name": "test",
        "url": "https://events.hookdeck.com/e/src_2Q0cNXCHyzPJCUOmpk76JKeU"
      },
      "resolved_rules": [
        {
          "type": "alert",
          "interval": 86400000,
          "strategy": "last_attempt"
        }
      ]
    }
  ]
}

Retrieve a webhook connection

URL Parameter

Parameter	Description
id	Webhook ID

GET /2021-08-01/connections/:id

Response Example

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T13:52:40.344Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "archived_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api"
  },
  "ruleset": {
    "id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2021-08-02T13:52:16.888Z",
    "created_at": "2021-08-01T21:29:36.367Z",
    "name": "default-ruleset",
    "rules": [
      {
        "type": "retry",
        "count": 5,
        "interval": 10800000,
        "strategy": "linear"
      },
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T13:52:17.030Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    },
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

Create a webhook connection

Body Parameters

Parameter	Type	Description
name	`string`	A unique name of the connection 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
rules	`Rule[]`	Array of rules to apply

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 /2021-08-01/connections

Request Body

{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "url": "https://example.com/webhook"
  }
}

Response Example

{
  "id": "web_3tVBgTFuuzmEnsWa9eBywz6j",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.575Z",
  "created_at": "2021-08-02T14:12:56.611Z",
  "paused_at": null,
  "name": "shopify-my-api",
  "rules": [],
  "destination": {
    "id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://example.com/webhook",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.591Z",
    "created_at": "2021-08-02T14:12:56.589Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": null,
    "path_forwarding_disabled": false,
    "name": "my-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.586Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2021-08-02T13:52:16.888Z",
    "created_at": "2021-08-01T21:29:36.367Z",
    "name": "default-ruleset",
    "rules": [
      {
        "type": "retry",
        "count": 5,
        "interval": 10800000,
        "strategy": "linear"
      },
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    },
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

Creating a webhook connection with a new source and destination

{
  "name": "github-some-api",
  "source": {
    "name": "github"
  },
  "destination": {
    "name": "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 name. 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
name	`string`	Unique name of the connection 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
rules	`Rule[]`	Array of rules to apply

PUT /2021-08-01/connections

Request Body

{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "url": "https://example.com/webhook"
  }
}

Response Example

{
  "id": "web_3tVBgTFuuzmEnsWa9eBywz6j",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.696Z",
  "created_at": "2021-08-02T14:12:56.611Z",
  "paused_at": null,
  "name": "shopify-my-api",
  "rules": [],
  "destination": {
    "id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://example.com/webhook",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.671Z",
    "created_at": "2021-08-02T14:12:56.589Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": null,
    "path_forwarding_disabled": false,
    "name": "my-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": true,
    "archived_at": null,
    "updated_at": "2021-08-02T13:52:16.888Z",
    "created_at": "2021-08-01T21:29:36.367Z",
    "name": "default-ruleset",
    "rules": [
      {
        "type": "retry",
        "count": 5,
        "interval": 10800000,
        "strategy": "linear"
      },
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    },
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

Update a webhook connection

This endpoint updates a webhook connection.

URL Parameter

Parameter	Description
id	Webhook ID

Body Parameters

Parameter	Type	Description
name	`string`	Unique name of the connection for the source
ruleset_id	`string`	ID of a rule to bind to the connection. Default to the Workspace default ruleset
ruleset	`Ruleset`	Ruleset input object
rules	`Rule[]`	Array of rules to apply

PUT /2021-08-01/connections/:id

Request Body

{
  "ruleset_id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ"
}

Response Example

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.748Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "archived_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": false,
    "archived_at": null,
    "updated_at": "2021-08-02T14:10:47.400Z",
    "created_at": "2021-08-02T14:10:47.399Z",
    "name": "example-ruleset",
    "rules": [
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

Pause a connection

This endpoint pauses a connection. A paused connection will still receive events but those events will be marked on HOLD and will not be delivered until the connection is unpaused.

URL Parameter

Parameter	Description
id	Connection ID

The parameter paused_at is set to the current timestamp.

PUT /2021-08-01/connections/:id/pause

Response Example

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.779Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": "2021-08-02T14:12:56.779Z",
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "archived_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": false,
    "archived_at": null,
    "updated_at": "2021-08-02T14:10:47.400Z",
    "created_at": "2021-08-02T14:10:47.399Z",
    "name": "example-ruleset",
    "rules": [
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

Unpause a connection

This endpoint unpauses a connection. The on HOLD events will be delivered immediately (throttled delivery configuration will be respected).

URL Parameter

Parameter	Description
id	Connection ID

The parameter paused_at is set to null

PUT /2021-08-01/connections/:id/unpause

Response Example

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.813Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "archived_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": false,
    "archived_at": null,
    "updated_at": "2021-08-02T14:10:47.400Z",
    "created_at": "2021-08-02T14:10:47.399Z",
    "name": "example-ruleset",
    "rules": [
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

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 /2021-08-01/connections/:id/archive

Response Example

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": "2021-08-02T14:12:56.779Z",
  "updated_at": "2021-08-02T14:12:56.779Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "archived_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": false,
    "archived_at": null,
    "updated_at": "2021-08-02T14:10:47.400Z",
    "created_at": "2021-08-02T14:10:47.399Z",
    "name": "example-ruleset",
    "rules": [
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

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 /2021-08-01/connections/:id/unarchive

Response Example

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.813Z",
  "created_at": "2021-08-01T21:29:41.818Z",
  "paused_at": null,
  "name": "mock-api",
  "rules": [],
  "destination": {
    "id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://mock.hookdeck.com",
    "archived_at": null,
    "updated_at": "2021-08-02T14:07:54.608Z",
    "created_at": "2021-08-01T21:29:41.785Z",
    "rate_limit": null,
    "rate_limit_period": "second",
    "cli_path": "/",
    "path_forwarding_disabled": false,
    "name": "mock-api"
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "archived_at": null,
    "updated_at": "2021-08-02T14:12:56.674Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
  },
  "ruleset": {
    "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "is_team_default": false,
    "archived_at": null,
    "updated_at": "2021-08-02T14:10:47.400Z",
    "created_at": "2021-08-02T14:10:47.399Z",
    "name": "example-ruleset",
    "rules": [
      {
        "type": "alert",
        "interval": 86400000,
        "strategy": "last_attempt"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

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 /2021-08-01/sources
GET /2021-08-01/sources/:id
POST /2021-08-01/sources
PUT /2021-08-01/sources
PUT /2021-08-01/sources/:id
PUT /2021-08-01/sources/:id/archive
PUT /2021-08-01/sources/:id/unarchive

Source object

Parameter	Type	Default	Description
id	`string`		ID of the source
team_id	`string`		ID of the workspace
name	`string`		Name 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",
  "name": "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
name	`string`	The source name
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 /2021-08-01/sources

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "src_2Q0cNXCHyzPJCUOmpk76JKeU"
  },
  "count": 1,
  "models": [
    {
      "id": "src_2Q0cNXCHyzPJCUOmpk76JKeU",
      "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
      "archived_at": null,
      "updated_at": "2021-08-01T21:48:16.865Z",
      "created_at": "2021-08-01T21:45:07.100Z",
      "name": "test",
      "url": "https://events.hookdeck.com/e/src_2Q0cNXCHyzPJCUOmpk76JKeU"
    }
  ]
}

Retrieve a source

URL Parameter

Parameter	Description
id	Webhook ID

GET /2021-08-01/sources/:id

Response Example

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.674Z",
  "created_at": "2021-08-01T21:29:41.788Z",
  "name": "shopify",
  "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}

Create a source

This endpoint creates a source.

Body Parameters

Parameter	Type	Description
name	`string`	A unique name for the source

POST /2021-08-01/sources

Request Body

{
  "name": "shopify"
}

Response Example

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.327Z",
  "created_at": "2021-08-01T21:29:41.788Z",
  "name": "shopify",
  "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}

Create/Update a source

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

Body Parameters

Parameter	Type	Description
name	`string`	A unique name for the source

PUT /2021-08-01/sources

Request Body

{
  "name": "shopify"
}

Response Example

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.327Z",
  "created_at": "2021-08-01T21:29:41.788Z",
  "name": "shopify",
  "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}

Update a source

This endpoint creates a source.

URL Parameter

Parameter	Description
id	Webhook ID

Body Parameters

Parameter	Type	Description
name	`string`	A unique name for the source

PUT /2021-08-01/sources/:id

Request Body

{
  "name": "shopify"
}

Response Example

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.347Z",
  "created_at": "2021-08-01T21:29:41.788Z",
  "name": "shopify",
  "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}

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 /2021-08-01/sources/:id/archive

Response Example

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": "2021-08-02T14:12:57.370Z",
  "updated_at": "2021-08-02T14:12:57.383Z",
  "created_at": "2021-08-01T21:29:41.788Z",
  "name": "shopify",
  "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}

Unarchive a source

URL Parameter

Parameter	Description
id	Source ID

The parameter archived_at is set to null

PUT /2021-08-01/sources/:id/unarchive

Response Example

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.406Z",
  "created_at": "2021-08-01T21:29:41.788Z",
  "name": "shopify",
  "url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}

Destinations

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

Endpoints

GET /2021-08-01/destinations
GET /2021-08-01/destinations/:id
POST /2021-08-01/destinations
PUT /2021-08-01/destinations
PUT /2021-08-01/destinations/:id
PUT /2021-08-01/destinations/:id/archive
PUT /2021-08-01/destinations/:id/unarchive

Destination object

Parameter	Type	Default	Description
id	`string`		ID of the destination
team_id	`string`		ID of the workspace
name	`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",
  "name": "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
name	`string`	The destination name
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 /2021-08-01/destinations

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "des_Nm49lhZV6wVrN1XFFPfkv7Zk"
  },
  "count": 1,
  "models": [
    {
      "id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
      "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
      "url": "https://example.com/webhook",
      "archived_at": null,
      "updated_at": "2021-08-02T14:12:56.671Z",
      "created_at": "2021-08-02T14:12:56.589Z",
      "rate_limit": null,
      "rate_limit_period": "second",
      "cli_path": null,
      "path_forwarding_disabled": false,
      "name": "my-api"
    }
  ]
}

Retrieve a destination

URL Parameter

Parameter	Description
id	Destination ID

GET /2021-08-01/destinations/:id

Response Example

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://mock.hookdeck.com",
  "archived_at": null,
  "updated_at": "2021-08-02T14:09:56.117Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "rate_limit": null,
  "rate_limit_period": "second",
  "cli_path": "/",
  "path_forwarding_disabled": false,
  "name": "example-destination"
}

Create a destination

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

Body Parameters

Parameter	Type	Description
name	`string`	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 /2021-08-01/destinations

Request Body

{
  "name": "my-api",
  "url": "https://example.com/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second"
}

Response Example

{
  "id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://example.com/webhook",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.933Z",
  "created_at": "2021-08-02T14:12:56.589Z",
  "rate_limit": 5,
  "rate_limit_period": "second",
  "cli_path": null,
  "path_forwarding_disabled": false,
  "name": "my-api"
}

Create/Update a destination

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

Body Parameters

Parameter	Type	Description
name	`string`	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 /2021-08-01/destinations

Request Body

{
  "name": "my-api",
  "url": "https://example.com/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second"
}

Response Example

{
  "id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://example.com/webhook",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.933Z",
  "created_at": "2021-08-02T14:12:56.589Z",
  "rate_limit": 5,
  "rate_limit_period": "second",
  "cli_path": null,
  "path_forwarding_disabled": false,
  "name": "my-api"
}

Update a destination

This endpoint updates a destination.

URL Parameter

Parameter	Description
id	Destination ID

Body Parameters

Parameter	Type	Description
name	`string`	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 /2021-08-01/destinations/:id

Request Body

{
  "name": "my-new-api"
}

Response Example

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://mock.hookdeck.com",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:56.960Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "rate_limit": null,
  "rate_limit_period": "second",
  "cli_path": "/",
  "path_forwarding_disabled": false,
  "name": "my-new-api"
}

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 /2021-08-01/destinations/:id/archive

Response Example

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://mock.hookdeck.com",
  "archived_at": "2021-08-02T14:12:57.042Z",
  "updated_at": "2021-08-02T14:12:57.042Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "rate_limit": null,
  "rate_limit_period": "second",
  "cli_path": "/",
  "path_forwarding_disabled": false,
  "name": "my-new-api"
}

Unarchive a destination

URL Parameter

Parameter	Description
id	Destination ID

The parameter archived_at is set to null

PUT /2021-08-01/destinations/:id/unarchive

Response Example

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://mock.hookdeck.com",
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.042Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "rate_limit": null,
  "rate_limit_period": "second",
  "cli_path": "/",
  "path_forwarding_disabled": false,
  "name": "my-new-api"
}

Rulesets

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

Endpoints

GET /2021-08-01/rulesets
GET /2021-08-01/rulesets/:id
POST /2021-08-01/rulesets
PUT /2021-08-01/rulesets
PUT /2021-08-01/rulesets/:id
PUT /2021-08-01/rulesets/:id/archive
PUT /2021-08-01/rulesets/:id/unarchive

Ruleset object

Parameter	Type	Default	Description
id	`string`		ID of the ruleset
team_id	`string`		ID of the workspace
name	`string`	`null`	A unique name for the ruleset
rules	`Rule[]`	`[]`	Array of rules to apply
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",
  "name": "default-ruleset",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    },
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ],
  "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 rulesets

Query Parameter

Parameter	Type	Description
id	`string[]`	Filter by ruleset ids
name	`string`	The ruleset name
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 /2021-08-01/rulesets

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "rls_YZCDPNVHORE8BZ86aDRyRMtZ"
  },
  "count": 1,
  "models": [
    {
      "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
      "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
      "is_team_default": false,
      "archived_at": null,
      "updated_at": "2021-08-02T14:10:47.400Z",
      "created_at": "2021-08-02T14:10:47.399Z",
      "name": "example-ruleset",
      "rules": [
        {
          "type": "alert",
          "interval": 86400000,
          "strategy": "last_attempt"
        }
      ]
    }
  ]
}

Retrieve a ruleset

URL Parameter

Parameter	Description
id	Ruleset ID

GET /2021-08-01/rulesets/:id

Response Example

{
  "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-08-02T14:10:47.400Z",
  "created_at": "2021-08-02T14:10:47.399Z",
  "name": "example-ruleset",
  "rules": [
    {
      "type": "alert",
      "interval": 86400000,
      "strategy": "last_attempt"
    }
  ]
}

Create a ruleset

This endpoint creates a ruleset.

Body Parameters

Parameter	Type	Description
name	`string`	Name for 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 /2021-08-01/rulesets

Request Body

{
  "name": "fast-retry-ruleset",
  "rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    },
    {
      "type": "alert",
      "interval": 3600000,
      "strategy": "last_attempt"
    }
  ]
}

Response Example

{
  "id": "rls_YreVNPlduZdaCIF1cDf2a11u",
  "name": "fast-retry-ruleset",
  "rules": [
    {
      "type": "retry",
      "count": 10,
      "interval": 60000,
      "strategy": "linear"
    },
    {
      "type": "alert",
      "interval": 3600000,
      "strategy": "last_attempt"
    }
  ],
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "created_at": "2021-08-02T14:12:57.131Z",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.132Z"
}

Create/Update a ruleset

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

Body Parameters

Parameter	Type	Description
name	`string`	Name for 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 /2021-08-01/rulesets

Request Body

{
  "name": "fast-retry-ruleset",
  "rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}

Response Example

{
  "id": "rls_YreVNPlduZdaCIF1cDf2a11u",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.156Z",
  "created_at": "2021-08-02T14:12:57.131Z",
  "name": "fast-retry-ruleset",
  "rules": [
    {
      "type": "retry",
      "count": 10,
      "interval": 60000,
      "strategy": "linear"
    }
  ]
}

Update a ruleset

This endpoint updates a ruleset.

URL Parameter

Parameter	Description
id	Ruleset ID

Body Parameters

Parameter	Type	Description
name	`string`	Naame for 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 /2021-08-01/rulesets/:id

Request Body

{
  "rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}

Response Example

{
  "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.183Z",
  "created_at": "2021-08-02T14:10:47.399Z",
  "name": "example-ruleset",
  "rules": [
    {
      "type": "retry",
      "count": 10,
      "interval": 60000,
      "strategy": "linear"
    }
  ]
}

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 /2021-08-01/rulesets/:id/archive

Response Example

{
  "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "is_team_default": false,
  "archived_at": "2021-08-02T14:12:57.236Z",
  "updated_at": "2021-08-02T14:12:57.236Z",
  "created_at": "2021-08-02T14:10:47.399Z",
  "name": "example-ruleset",
  "rules": [
    {
      "type": "retry",
      "count": 10,
      "interval": 60000,
      "strategy": "linear"
    }
  ]
}

Unarchive a ruleset

URL Parameter

Parameter	Description
id	Ruleset ID

The parameter archived_at is set to null

PUT /2021-08-01/rulesets/:id/unarchive

Response Example

{
  "id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "is_team_default": false,
  "archived_at": null,
  "updated_at": "2021-08-02T14:12:57.236Z",
  "created_at": "2021-08-02T14:10:47.399Z",
  "name": "example-ruleset",
  "rules": [
    {
      "type": "retry",
      "count": 10,
      "interval": 60000,
      "strategy": "linear"
    }
  ]
}

Events

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

Endpoints

GET /2021-08-01/events
GET /2021-08-01/events/:id
POST /2021-08-01/events/:id/retry
PUT /2021-08-01/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

Filtering by dates

Date filters only support operators. For example, to retrieves events for a specific date, you would need to append the following query ?created_at[gte]=2021-10-12&created_at[lte]=2021-10-13

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`	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 operator
successful_at	`date`	Filter by last_attempt_at date using a date operator
last_attempt_at	`date`	Filter by last_attempt_at date using a date operator
next_attempt_at	`date`	Filter by next_attempt_at date using a date operator
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 /2021-08-01/events

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "evt_njCeMZHzNhJWdkkZ7PLCfEw5"
  },
  "count": 1,
  "models": [
    {
      "id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
      "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
      "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
      "source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
      "destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
      "attempts": 4,
      "response_status": 422,
      "last_attempt_at": "2021-08-02T13:52:16.439Z",
      "next_attempt_at": null,
      "successful_at": "2021-08-01T21:56:35.181Z",
      "updated_at": "2021-08-02T13:52:16.813Z",
      "created_at": "2021-08-01T21:44:57.513Z",
      "status": "FAILED",
      "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
      "cli_id": null
    }
  ]
}

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 /2021-08-01/events/:id

Response Example

{
  "id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
  "attempts": 4,
  "response_status": 422,
  "last_attempt_at": "2021-08-02T13:52:16.439Z",
  "next_attempt_at": null,
  "successful_at": "2021-08-01T21:56:35.181Z",
  "updated_at": "2021-08-02T13:52:16.813Z",
  "created_at": "2021-08-01T21:44:57.513Z",
  "status": "FAILED",
  "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "cli_id": null,
  "request": {
    "headers": {
      "content-length": "20",
      "x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
      "cookie": "",
      "x-client-version": "FirebaseCLI/undefined",
      "content-type": "application/json",
      "user-agent": "FirebaseCLI/undefined"
    },
    "body": {
      "test": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  }
}

Retry an event

This endpoint manually queues an event for retry.

URL Parameter

Parameter	Description
id	Event ID

POST /2021-08-01/events/:id/retry

Response Example

{
  "event": {
    "id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
    "source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "attempts": 4,
    "response_status": 422,
    "last_attempt_at": "2021-08-02T13:52:16.439Z",
    "next_attempt_at": null,
    "successful_at": "2021-08-01T21:56:35.181Z",
    "updated_at": "2021-08-02T14:12:56.321Z",
    "created_at": "2021-08-01T21:44:57.513Z",
    "status": "QUEUED",
    "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
    "cli_id": null,
    "request": {
      "headers": {
        "content-length": "20",
        "x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
        "cookie": "",
        "x-client-version": "FirebaseCLI/undefined",
        "content-type": "application/json",
        "user-agent": "FirebaseCLI/undefined"
      },
      "body": {
        "test": true
      },
      "query": "",
      "parsed_query": {},
      "path": "/"
    }
  },
  "attempt": {
    "id": "atm_bfD1fTzCmj9nfiRNQ4j6YqHV",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "event_id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
    "response_status": null,
    "successful_at": null,
    "updated_at": "2021-08-02T14:12:56.319Z",
    "created_at": "2021-08-02T14:12:56.353Z",
    "error_code": null,
    "bulk_retry_id": null,
    "status": "QUEUED",
    "trigger": "MANUAL",
    "attempt_number": 5,
    "delivered_at": null,
    "responded_at": null,
    "delivery_latency": null,
    "response_latency": null,
    "attemptResponse": null
  }
}

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 /2021-08-01/events/:id/mute

Response Example

{
  "id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
  "attempts": 5,
  "response_status": 422,
  "last_attempt_at": "2021-08-02T13:52:16.439Z",
  "next_attempt_at": null,
  "successful_at": "2021-08-01T21:56:35.181Z",
  "updated_at": "2021-08-02T14:12:56.466Z",
  "created_at": "2021-08-01T21:44:57.513Z",
  "status": "QUEUED",
  "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "cli_id": null,
  "request": {
    "headers": {
      "content-length": "20",
      "x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
      "cookie": "",
      "x-client-version": "FirebaseCLI/undefined",
      "content-type": "application/json",
      "user-agent": "FirebaseCLI/undefined"
    },
    "body": {
      "test": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  }
}

Attempts

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

Endpoints

GET /2021-08-01/attempts
GET /2021-08-01/attempts/:id
GET /2021-08-01/attempts
GET /2021-08-01/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 /2021-08-01/attempts

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "atm_NgrzbX4NcfazxAigdhb8KBXr"
  },
  "count": 1,
  "models": [
    {
      "id": "atm_NgrzbX4NcfazxAigdhb8KBXr",
      "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
      "event_id": "evt_vuHxr759DYe6LsBgDk2VOfqI",
      "response_status": null,
      "successful_at": null,
      "updated_at": "2021-08-02T14:12:57.658Z",
      "created_at": "2021-08-02T14:12:57.631Z",
      "error_code": null,
      "bulk_retry_id": null,
      "status": "QUEUED",
      "trigger": "INITIAL",
      "attempt_number": 1,
      "delivered_at": null,
      "responded_at": null,
      "delivery_latency": null,
      "response_latency": null
    }
  ]
}

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 /2021-08-01/attempts/:id

Response Example

{
  "id": "atm_kgHSGmGMTXGfQhKArm77tRIp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "event_id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
  "response_status": 202,
  "successful_at": "2021-08-01T21:56:35.181Z",
  "updated_at": "2021-08-01T21:56:35.185Z",
  "created_at": "2021-08-01T21:56:34.905Z",
  "error_code": null,
  "bulk_retry_id": null,
  "status": "SUCCESSFUL",
  "trigger": "MANUAL",
  "attempt_number": 2,
  "delivered_at": "2021-08-01T21:56:35.015Z",
  "responded_at": "2021-08-01T21:56:35.181Z",
  "delivery_latency": 110,
  "response_latency": 166,
  "body": {
    "message": "The Mock API returns the request data with a randomized status code",
    "next_step": "Convinced? Update your destination with your own server HTTP URL.",
    "mock_status": 202,
    "requested_path": "/",
    "received_data": {
      "headers": {
        "host": "mock.hookdeck.com",
        "connection": "close",
        "accept": "application/json, text/plain, */*",
        "content-type": "application/json",
        "idempotency-key": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
        "x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
        "cookie": "",
        "x-client-version": "FirebaseCLI/undefined",
        "user-agent": "FirebaseCLI/undefined",
        "x-hookdeck-eventid": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
        "x-hookdeck-attempt-count": "2",
        "x-hookdeck-event-url": "http://localhost:3000/events/evt_njCeMZHzNhJWdkkZ7PLCfEw5",
        "x-hookdeck-signature": "Yhj7PMxNwFtNhZMQ6MFeLJsmC51li2aO4zanCwdld7I=",
        "x-hookdeck-source-name": "shopify",
        "x-newrelic-id": "VwQGVlRVDRAFVlJWBggGX1c=",
        "x-newrelic-transaction": "PxQOWVRRAVBUAQUAUVVWVgACFB8EBw8RVU4aWwAKBgtQAVwFUwdXA1RSBENKQQ9SBgFQBw4AFTs=",
        "x-request-id": "fed4b172-12f9-4a2d-b629-9de008b2e471",
        "x-forwarded-for": "135.19.54.44",
        "x-forwarded-proto": "https",
        "x-forwarded-port": "443",
        "via": "1.1 vegur",
        "connect-time": "0",
        "x-request-start": "1627854995250",
        "total-route-time": "0",
        "content-length": "20"
      },
      "body": {
        "test": true
      },
      "query": {}
    }
  },
  "requested_url": "https://mock.hookdeck.com/"
}

Bulk

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

Endpoints

POST /2021-08-01/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 /2021-08-01/bulk/events/retry

Request Body

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

Response Example

{
  "id": "blkret_oDYLIXvbguDuaJ73JiEPk55q",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "query": {
    "dir": "desc",
    "limit": 2,
    "headers": "{\"user-agent\":\"PostmanRuntime/7.26.8\"}",
    "order_by": "created_at"
  },
  "updated_at": "2021-08-02T14:12:57.792Z",
  "created_at": "2021-08-02T14:12:57.791Z",
  "processed": [],
  "unprocessed": []
}

Bookmarks

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

Endpoints

GET /2021-08-01/bookmarks
GET /2021-08-01/bookmarks/:id
POST /2021-08-01/bookmarks
PUT /2021-08-01/bookmarks/:id
POST /2021-08-01/bookmarks/:id/trigger
DELETE /2021-08-01/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
name	`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",
  "name": 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
name	`string`	Filter by bookmark name
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 /2021-08-01/bookmarks

Response Example

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1
  },
  "count": 0,
  "models": []
}

Retrieve a bookmark

URL Parameter

Parameter	Description
id	Bookmark ID

GET /2021-08-01/bookmarks/:id

Response Example

{
  "id": "bmk_4RbrZcXNALN6WKUljj92hY08",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "label": "Shopify order",
  "alias": null,
  "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "last_used_at": null,
  "updated_at": "2021-08-02T13:43:23.518Z",
  "created_at": "2021-08-02T13:43:23.516Z",
  "request": {
    "headers": {
      "content-length": "20",
      "x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
      "cookie": "",
      "x-client-version": "FirebaseCLI/undefined",
      "content-type": "application/json",
      "user-agent": "FirebaseCLI/undefined"
    },
    "body": {
      "test": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  }
}

Create a bookmark

Body Parameters

Parameter	Type	Description
label	`string`	Name of the bookmark
alias?	`string`	Alternate alias for the bookmark
webhook_id	`string`	ID of the associated connection
event_request_id	`string`	ID of the event request to bookmark

POST /2021-08-01/bookmarks

Request Body

{
  "label": "Product Update – Out of Stock",
  "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp"
}

Response Example

{
  "id": "bmk_pgmwVfQ9faN975poe0kW1Sp4",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "label": "Product Update – Out of Stock",
  "alias": null,
  "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "last_used_at": null,
  "updated_at": "2021-08-02T14:12:57.521Z",
  "created_at": "2021-08-02T14:12:57.520Z",
  "request": {
    "headers": {
      "content-length": "20",
      "x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
      "cookie": "",
      "x-client-version": "FirebaseCLI/undefined",
      "content-type": "application/json",
      "user-agent": "FirebaseCLI/undefined"
    },
    "body": {
      "test": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  }
}

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`	Alternate alias for the bookmark
webhook_id	`string`	ID of the associated connection
event_request_id	`string`	ID of the event request to bookmark

PUT /2021-08-01/bookmarks/:id

Request Body

{
  "label": "Product Update – Out of Stock",
  "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp"
}

Response Example

{
  "id": "bmk_4RbrZcXNALN6WKUljj92hY08",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "label": "Product Update – Out of Stock",
  "alias": null,
  "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "last_used_at": null,
  "updated_at": "2021-08-02T14:12:57.545Z",
  "created_at": "2021-08-02T13:43:23.516Z",
  "request": {
    "headers": {
      "content-length": "20",
      "x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
      "cookie": "",
      "x-client-version": "FirebaseCLI/undefined",
      "content-type": "application/json",
      "user-agent": "FirebaseCLI/undefined"
    },
    "body": {
      "test": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  }
}

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`	`cli` or `http`

The parameter last_used_at is set to the current timestamp.

POST /2021-08-01/bookmarks/:id/trigger

Response Example

[
  {
    "id": "evt_vuHxr759DYe6LsBgDk2VOfqI",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
    "source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
    "attempts": 0,
    "response_status": null,
    "last_attempt_at": null,
    "next_attempt_at": null,
    "successful_at": null,
    "updated_at": "2021-08-02T14:12:57.595Z",
    "created_at": "2021-08-02T14:12:57.610Z",
    "status": "QUEUED",
    "event_request_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
    "cli_id": null,
    "request": {
      "headers": {
        "content-length": "20",
        "x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
        "cookie": "",
        "x-client-version": "FirebaseCLI/undefined",
        "content-type": "application/json",
        "user-agent": "FirebaseCLI/undefined"
      },
      "body": {
        "test": true
      },
      "query": "",
      "parsed_query": {},
      "path": "/"
    }
  }
]

Delete a bookmark

Deleting a bookmark won't affect the triggered events.

URL Parameter

Parameter	Description
id	Bookmark ID

DELETE /2021-08-01/bookmarks/:id

Response Example

"bmk_4RbrZcXNALN6WKUljj92hY08"

Rule

A rule can be applied to either a Ruleset or Connection rules field. Each rule as a required type which is unique to that resource rules.

Retry

A retry rule will apply automatic retry to failed events associated with that connection or ruleset. The properties for a retry rules are:

Parameter	Type	Description
type	`retry`	A retry rule must be of type `retry`
strategy	`linear` `exponential`	Algorithm to use when calculating delay between retries
count	`number`	Maximum number of retries to attempt
interval	`number`	Time in MS between each retry

{
  "type": "retry",
  "strategy": "linear",
  "count": 5,
  "interval": 60000
}

Alert

A alert rule will configure an email alert to be sent when attempt error occur. The properties for a alert rules are:

Parameter	Type	Description
type	`alert`	A alert rule must be of type `alert`
strategy	`each_attempt` `last_attempt`	Algorithm to use when deciding to sent an alert
interval	`number`	Maximum time in MS between each alert

{
  "type": "alert",
  "strategy": "each_attempt",
  "interval": 60000
}

Filter

A filter rule will configure a filter on incoming events. The properties for a filter rules are:

Parameter	Type	Description
type	`filter`	A filter rule must be of type `filter`
body?	`JSON`	JSON using our filter syntaxt to filter on request body
headers?	`JSON`	JSON using our filter syntaxt to filter on request headers
path?	`JSON`	JSON using our filter syntaxt to filter on request path
query?	`JSON`	JSON using our filter syntaxt to filter on request parsed query params

{
  "type": "filter",
  "body": {
    "example": true
  }
}

Get In Touch

Reach out by using the live chat in the bottom right corner or contact the Hookdeck team by email at [email protected]!