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

ParameterTypeDescription
namestringName of the webhook

Source

ParameterTypeDescription
namestringName of the source

Destination

One of url or cli_path is mandatory

ParameterTypeDescription
namestringName of the destination
urlurlEndpoint of the destination
cli_pathstringPath 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.

ParameterDefaultDescription
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")
limit100The making amount of results returned per query (max: 250)
nextundefinedThe ID to provide in the query to get the next set of results
prevundefinedThe ID to provide in the query to get the previous set of results
nextundefinedThe cursor to provide in the query to get the next set of results
previousundefinedThe 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.

ParameterTypeDescription
handlebooleanError was handled by the API and did not resolve in an uncaught exception.
statusintegerHTTP Status of the error
messagestringMessage associated with the error, could be more or less specific depending on the error
dataobjectData related to the error, useful for diagnostics

Error Codes

Status CodeExplanation
200Good Request -- Your request is valid.
400Bad Request -- Your request is invalid and could not be understood.
401Unauthorized -- Your API key is wrong.
403Forbidden -- The resource requested access is restricted.
404Not Found -- The resource could not be found.
422Unprocessable Entry -- Your request was understood but contains invalid input.
500Internal Server Error -- We had a problem with our server. Try again later.
503Service 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:

ParameterSupported TypesDescription
gtedate numberGreater or equal then
gtdate numberGreater then
ltedate numberLesser or equal then
ltdate numberLesser then
anydate number stringNot 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

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.

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

ParameterTypeDefaultDescription
idstringID of the connection
namestringUnique name of the connection for this source
team_idstringID of the workspace
sourceSourceAssociated Source object
destinationDestinationAssociated Destination object
rulesetRulesetWorkspace default rulesetAssociated Ruleset object
archived_atISO DatenullDate the webhook was archived
updated_atISO DateLast ISO Date the webhook was updated
created_atISO DateDate the webhook was created
resolved_rulesRule[][]Array of rules applied to connection after factoring for the ruleset
rulesRule[][]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

ParameterTypeDescription
idstring[]Filter by connection ids
archivedbooleanInclude the archived resources in response
archived_atdateDate the connection was archived
limitnumberLimit 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

ParameterDescription
idWebhook 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

ParameterTypeDescription
namestringA unique name of the connection for the source
source_idstringID of a source to bind to the connection
destination_idstringID of a destination to bind to the connection
ruleset_idstringID of a rule to bind to the connection. Default to the Workspace default ruleset
sourceSourceSource input object
destinationDestinationDestination input object
rulesetRulesetRuleset input object
rulesRule[]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.

ParameterTypeDescription
namestringUnique name of the connection for the source
source_idstringID of a source to bind to the connection
destination_idstringID of a destination to bind to the connection
ruleset_idstringID of a rule to bind to the connection. Default to the Workspace default ruleset
sourceSourceSource input object
destinationDestinationDestination input object
rulesetRulesetRuleset input object
rulesRule[]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

ParameterDescription
idWebhook ID

Body Parameters

ParameterTypeDescription
namestringUnique name of the connection for the source
ruleset_idstringID of a rule to bind to the connection. Default to the Workspace default ruleset
rulesetRulesetRuleset input object
rulesRule[]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

ParameterDescription
idConnection 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

ParameterDescription
idConnection 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

ParameterDescription
idConnection 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

ParameterDescription
idConnection 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

ParameterTypeDefaultDescription
idstringID of the source
team_idstringID of the workspace
namestringName for the source
archived_atdatenullDate the source was archived
updated_atdateISO Last ISO Date the source was updated
created_atdateISO 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

ParameterTypeDescription
idstring[]Filter by source ids
namestringThe source name
archivedbooleanInclude the archived resources in response
archived_atdateDate the source was archived
limitnumberLimit 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

ParameterDescription
idWebhook 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

ParameterTypeDescription
namestringA 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

ParameterTypeDescription
namestringA 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

ParameterDescription
idWebhook ID

Body Parameters

ParameterTypeDescription
namestringA 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

ParameterDescription
idSource 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

ParameterDescription
idSource 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

ParameterTypeDefaultDescription
idstringID of the destination
team_idstringID of the workspace
namestringA unique, human friendly id for the destination
urlurlHTTP Endpoint of the destination
cli_pathstringPath for the CLI destination
rate_limitnumberLimit event attempts to receive per period. Max 100/second or 6000/minute
rate_limit_periodstring'second'Period to rate limit attempts. (second or minute)
archived_atISO DatenullDate the destination was archived
updated_atISO DateLast ISO Date the destination was updated
created_atISO DateDate 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

ParameterTypeDescription
idstring[]Filter by destination ids
namestringThe destination name
archivedbooleanInclude the archived resources in response
archived_atdateDate the destination was archived
urlstringHTTP Endpoint of the destination
cli_pathstringPath for the CLI destination
limitnumberLimit 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

ParameterDescription
idDestination 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

ParameterTypeDescription
namestringName for the destination
urlurlEndpoint of the destination
cli_pathstringPath for the CLI destination
rate_limitnumberLimit event attempts to receive per period. Max 100/second or 6000/minute
rate_limit_periodstringPeriod 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

ParameterTypeDescription
namestringName for the destination
urlurlEndpoint of the destination
rate_limitnumberLimit event attempts to receive per period. Max 100/second or 6000/minute
rate_limit_periodstringPeriod 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

ParameterDescription
idDestination ID

Body Parameters

ParameterTypeDescription
namestringName for the destination
urlurlEndpoint of the destination
cli_pathstringPath for the CLI destination
rate_limitnumberLimit event attempts to receive per period. Max 100/second or 6000/minute
rate_limit_periodstringPeriod 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

ParameterDescription
idDestination 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

ParameterDescription
idDestination 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

ParameterTypeDefaultDescription
idstringID of the ruleset
team_idstringID of the workspace
namestringnullA unique name for the ruleset
rulesRule[][]Array of rules to apply
is_team_defaultbooleantrueDefault ruleset of Workspace
archived_atdatenullDate the ruleset was archived
updated_atdateLast ISO Date the ruleset was updated
created_atdateDate 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

ParameterTypeDescription
idstring[]Filter by ruleset ids
namestringThe ruleset name
archivedbooleanInclude the archived resources in response
archived_atdateDate the ruleset was archived
limitnumberLimit 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

ParameterDescription
idRuleset 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

ParameterTypeDescription
namestringName for the ruleset
retry_countintegerNumber of retry attempts
retry_intervalintegerTime interval between retries in ms. Min 60000
alert intervalintegerTime interval between alerts in ms
alert strategystringAlert 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

ParameterTypeDescription
namestringName for the ruleset
retry_countintegerNumber of retry attempts
retry_intervalintegerTime interval between retries in ms. Min 60000
alert intervalintegerTime interval between alerts in ms
alert strategystringAlert 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

ParameterDescription
idRuleset ID

Body Parameters

ParameterTypeDescription
namestringNaame for the ruleset
retry_countintegerNumber of retry attempts
retry_intervalintegerTime interval between retries in ms. Min 60000
alert intervalintegerTime interval between alerts in ms
alert strategystringAlert 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

ParameterDescription
idRuleset 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

ParameterDescription
idRuleset 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

ParameterTypeDefaultDescription
idstringID of the event
team_idstringID of the workspace
webhook_idstringID of the associated connection
source_idstringID of the associated source
destination_idstringID of the associated destination
cli_idstringnullID of the CLI the event is sent to
event_request_idstringID of the request data
attemptsnumber0Number of delivery attempts made
statusstringnullLifecyle status of the event. One of QUEUED, HOLD, SUCCESSFUL, FAILED
response_statusnumbernullEvent status
error_codestringnullNone HTTP error code.
last_attempt_atdatenullLast date a retry was attempted
next_attempt_atdatenullNext date of a scheduled retry
sucessful_atdatenulldate of the latest successful attempt
updated_atdateLast date the event was updated
created_atdateDate 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

ParameterTypeDescription
idstring[]Filter by event ids
webhook_idstring[]Filter by webhook connection ids
source_idstring[]Filter by source ids
destination_idstring[]Filter by destination ids
cli_idstring[]Filter by cli ids. ?[any]=true operator for any CLI. Defaults to null
statusstringLifecyle status of the event. One of QUEUED, HOLD, SUCCESSFUL, FAILED
response_statusnumberFilter by HTTP response status code
attemptsnumberFilter by number of attempts
created_atdateFilter by created_at date using a date operator
successful_atdateFilter by last_attempt_at date using a date operator
last_attempt_atdateFilter by last_attempt_at date using a date operator
next_attempt_atdateFilter by next_attempt_at date using a date operator
bodyJSONURL Encoded string of the JSON to match to the request body
headersJSONURL Encoded string of the JSON to match to the request headers
parsed_queryJSONURL Encoded string of the JSON to match to the parsed query (JSON representation of the query)
pathstringURL Encoded string of the string to match partially to the path
limitstringLimit the returned event count. Max 250.
order_bystringSort 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

ParameterDescription
idEvent 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

ParameterDescription
idEvent 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

ParameterDescription
idEvent 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

ParameterTypeDefaultDescription
idstringAttempt ID
team_idstringDeck ID
event_idstringEvent ID
error_codestringAttempt could not complete because of an error
sucessful_atISO DatenullDate of the successful event
updated_atISO DateLast ISO Date the event was updated
created_atISO DateDate 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

ParameterTypeDescription
event_idstring[]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

ParameterDescription
idAttempt 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

ParameterTypeDefaultDescription
dry_runbooleantrueReturns events to be retried by the query without retrying
idstring[]Filter by event ids
webhook_idstring[]Filter by webhook connection ids
source_idstring[]Filter by source ids
destination_idstring[]Filter by destination ids
response_statusnumberFilter by response status
attemptsnumberFilter by number of attempts
created_atdateFilter by created_at date using a date
successful_atdateFilter by last_attempt_at date using a date
last_attempt_atdateFilter by last_attempt_at date using a date
next_attempt_atdateFilter by next_attempt_at date using a date
bodyJSONJSON to match to the request body
headersJSONJSON to match to the request headers
parsed_queryJSONJSON to match to the parsed query (JSON representation of the query)
pathstringString to match partially to the path
limitstringLimit the returned event count. Max 250.
dirstringdescThe direction to sort it ("asc" or "desc")
order_bystringcreated_atSort by created_at (default) or last_attempt_at.
nextstringThe ID to provide in the query to get the next set of results
prevstringThe 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

ParameterTypeDefaultDescription
idstringID of the bookmark
team_idstringID of the workspace
labelstringDescriptive name of the bookmark
namestringA unique, human friendly id for the bookmark
webhook_idstringID of the associated connection
event_request_idstringID of the bookmarked event request
last_used_atISO DatenullLast ISO Date the bookmark was manually triggered
updated_atISO DateLast ISO Date the bookmark was updated
created_atISO DateDate 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

ParameterTypeDescription
idstringFilter by bookmark ids
namestringFilter by bookmark name
webhook_idstringFilter by associated connection ID
event_request_idstringFilter by associated event request ID
labelstringFilter by label
last_used_atDateFilter by last used date
limitnumberLimit 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

ParameterDescription
idBookmark 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

ParameterTypeDescription
labelstringName of the bookmark
alias?stringAlternate alias for the bookmark
webhook_idstringID of the associated connection
event_request_idstringID 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

ParameterDescription
idBookmark ID

Body Parameters

ParameterTypeDescription
labelstringName of the bookmark
alias?stringAlternate alias for the bookmark
webhook_idstringID of the associated connection
event_request_idstringID 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

ParameterDescription
idBookmark ID

Body Parameters

ParameterTypeDescription
target?stringcli 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

ParameterDescription
idBookmark 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:

ParameterTypeDescription
typeretryA retry rule must be of type retry
strategylinear exponentialAlgorithm to use when calculating delay between retries
countnumberMaximum number of retries to attempt
intervalnumberTime 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:

ParameterTypeDescription
typealertA alert rule must be of type alert
strategyeach_attempt last_attemptAlgorithm to use when deciding to sent an alert
intervalnumberMaximum 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:

ParameterTypeDescription
typefilterA filter rule must be of type filter
body?JSONJSON using our filter syntaxt to filter on request body
headers?JSONJSON using our filter syntaxt to filter on request headers
path?JSONJSON using our filter syntaxt to filter on request path
query?JSONJSON 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]!