Hookdeck

Getting Started

The Hookdeck REST API allows you to set up connections, retrieve events, and perform actions programmatically.

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.

Get an API key

You'll need to include an API key in every API request. If you do not yet have a Hookdeck account, please sign up for a free account. Your API key is located in your workspace settings.

To include your API key in requests, use either Bearer Token Authentication or Basic Authentication.

MethodProcedure
Bearer Token AuthenticationInclude the header Authorization: Bearer $API_KEY, replacing $API_KEY with your personal key
Basic AuthenticationSet the username as your API key, and supply an empty password
Terminal
curl "https://api.hookdeck.com/2023-01-01/events"
  -H "Content-Type: application/json"
  -H "Authorization: Bearer $API_KEY"

Create your first connection

Creating your first connection will allow you to start routing webhooks with Hookdeck.

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

Required parameters

ParameterTypeDescription
namestringName of the new connection
source.namestringName of the source to create
destination.namestringName of the destination to create
destination.urlstringHTTP endpoint of the destination
destination.cli_pathstringPath for the CLI destination

Only one of url or cli_path is required.

Response

The response body returns objects for the associated source, destination, and ruleset.

These resources can be reused in future requests by passing the destination_id, source_id, or ruleset_id instead of an object.

Endpoint
HTTP
POST /2023-01-01/connections
Request body example
JSON
{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "url": "https://example.com/webhook"
  }
}
Response example
JSON
{
  "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"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    }
  ]
}
Example reusing resources
JSON
{
  "name": "shopify-my-api",
  "destination_id": "des_xxxxxxxxxxxxxxx",
  "source_id": "src_xxxxxxxxxxxxxxx",
  "ruleset_id": "rls_xxxxxxxxxxxxxxx"
}

Verify your first connection

Verifying the connection lets you know Hookdeck is properly ingesting and processing webhooks from your source.

Copy the unique Hookdeck URL and paste it into your API provider's webhook URL field. Test the connection by triggering a webhook on your source. As soon Hookdeck receives your first webhook, it'll appear in your dashboard.

The connection URL is a property of the webhook source object.

Congratulations! Your webhook events can now be viewed, inspected, filtered, sorted, retried, and more using Hookdeck.

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

Authentication

Your API key is located in your workspace settings, and must be included in every API request. Use either Bearer Token Authentication or Basic Authentication.

MethodProcedure
Bearer Token AuthenticationInclude the header Authorization: Bearer $API_KEY, replacing $API_KEY with your personal key
Basic AuthenticationSet the username as your API key, and supply an empty password
Terminal
curl "https://api.hookdeck.com/2023-01-01/events"
  -H "Content-Type: application/json"
  -H "Authorization: Bearer $API_KEY"

Paging

All GET endpoints that retrieve a list of resources are paged using cursor (aka keyset) pagination, which resides in the response body's 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

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.

Pagination object
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100,
    "next": "web_2urj7h9puxk6obro3x",
    "prev": "web_2urj7h9puxk6obuf6i"
  }
}
Example to get the next page
Terminal
curl "https://api.hookdeck.com/2023-01-01/connections?next=web_2urj7h9puxk6obro3x"
  -H "Authorization: Basic BASE64_API_TOKEN"
Example to get the previous page
Terminal
curl "https://api.hookdeck.com/2023-01-01/connections?previous=web_2urj7h9puxk6obuf6i"
  -H "Authorization: Basic BASE64_API_TOKEN"
Example to get the next page without using the default ordering
Terminal
curl "https://api.hookdeck.com/2023-01-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.

ParameterTypeDescription
handlebooleanError was handled by the API and did not resolve in an uncaught exception
statusintegerHTTP status code for the error
messagestringAny message associated with the error
dataobjectAny data related to the error, useful for diagnostics

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. See a more complete list of error codes here.

Example response from an error
JSON
{
  "handled": true,
  "status": 422,
  "message": "Webhook does not exist or is archived",
  "data": {
    "id": "web_xxxxxxxxxxx"
  }
}

Rate Limits

The Hookdeck API has a rate limit of 240 request per minute, per API key. Contact us if you need your rate limit increased.

Rate limiting response headers
text
Retry-After: Seconds before next request can be made
X-RateLimit-Limit: Request per minute limit for the API key
X-RateLimit-Remaining: Remaining request for the rate limit period
X-RateLimit-Reset: ISO timestamp of the next rate limit period reset

Query Formatting

Arrays

Arrays in query parameters are indicated by a [] appended to their type, like string[].

For example: ?item[1]=hello&item[2]=world becomes ["hello", "world"]

Date

Dates are expected in ISO format.

For example: 2021-01-21T20:16:28Z or 2021-01-21

JSON

Some query parameters take JSON as input. The JSON should be stringified and URL encoded.

For example: ?body=%7B%0A%20%20"hello"%3A%20"world"%0A%7D becomes { "hello": "world" }

Operators

Most GET endpoints that retrieve a list of resources support operators as part of the request query.

For example: ?number[gte]=1&number[lte]=10

OperatorSupported TypesDescription
gtedate numberGreater than or equal to
gtdate numberGreater than
ltedate numberLesser than or equal to
ltdate numberLesser than
anydate number stringNot null
containsstringContains

Changelog

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

The API version can be set in the base path of any endpoint, such as $API_BASE_URL/sources. Otherwise the API defaults to the oldest supported stable version.

The backwards-incompatible changes for each version are listed below. Backwards-compatible changes don’t need a new API version and do not appear in this list.

2023-01-01

  • Remove alert rule type from rules on Rulesets and Connections.
  • Added "Issue Triggers" to configure when issues are opened and closed.

2022-11-01

  • Changed the string responses of DELETE operations on /bookmarks/:id and /integrations/:id to { "id": "SOME_ID" } instead of ID to prevent error with unstructured response with some clients.
  • Changed the boolean responses of PUT operations on /integrations/:id/attach/:source_id" and /integrations/:id/detach/:source_id" to { "success": true } instead of true to prevent error with unstructured response with some clients.
  • Changed the number responses of GET operations on /issues/count to { "count": 123 } instead of 123 to prevent error with unstructured response with some clients.

2022-10-01

  • Remove the properties completed_event_id and last_processed_event_id from the Event Bulk Retry model
  • Renamed the following properties on the Event Bulk Retry model
    • estimated_batch_count to estimated_batch
    • processed_batch_count to processed_batch
    • estimated_event_count to estimated_count
    • delivered_event_count to completed_count
    • failed_event_count to failed_count
  • Added bulk retries for requests

2022-07-01

  • Renamed the request property to data on Events and Bookmarks
  • Renamed the request value to data when querying events with the data included, such that /events?include=request is now /events?include=data
  • Renamed the event_request_id property on Events and Bookmarks to event_data_id

Introducing the Requests endpoint

  • You can now use the Requests endpoint to retrieve the original requests that were received by Hookdeck, along with their associated events (including ignored events).

2022-03-01

  • Removed the interval property from the Alert rule. Alert rule now controls how new issues are opened and notifications are now triggered by an issue opening or re-opening.

Introducing Issues

  • You can now use the Issues endpoint to retrieve, update, and dismiss problems within your workspace.

Introducing Notifications by webhook

  • You can now use the Notifications endpoint to configure webhook notifications for your workspace.

2021-08-01

Introducing Rules

The removed properties of Rulesets and Connections have been replaced by the rules array. Each rule has a type and a set of properties to configure its behavior. Rule definitions are here.

2020-01-01

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

OpenAPI Schema

Our OpenAPI schema is available at https://api.hookdeck.com/openapi.

This URL always returns the schema for the latest version of the API

OpenAPI schemas can be used to generate SDKs for your language of choice and work with various tools made for OpenAPI definitions such as importing into Postman.

Connections

A connection lets you route webhooks from a source to a destination, using a ruleset.

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

Endpoints
HTTP
GET /2023-01-01/connections
GET /2023-01-01/connections/:id
POST /2023-01-01/connections
PUT /2023-01-01/connections
PUT /2023-01-01/connections/:id
PUT /2023-01-01/connections/:id/archive
PUT /2023-01-01/connections/:id/unarchive
PUT /2023-01-01/connections/:id/pause
PUT /2023-01-01/connections/:id/unpause

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_atdatenullDate the connection was archived
updated_atdateDate the connection was last updated
created_atdateDate the connection was created
resolved_rulesRule[][]Array of rules applied to connection after factoring for the ruleset
rulesRule[][]Array of rules configured on the connection
JSON
{
  "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"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    }
  ]
}

Retrieve all connections

This endpoint lists all connections, or a subset of connections.

Query Parameters

ParameterTypeDescription
idstring[]Filter by connection IDs
namestringFilter by connection name
full_namestringFuzzy match the concatenated source and connection name. The source name and connection name must be separated by " -> "
source_idstring[]Associated Source ID
destination_idstring[]Associated Destination id
archivedbooleanInclude archived resources in the response
archived_atdateDate the connection was archived
paused_atdateDate the connection was paused
limitnumberLimit the returned event count (max 250)
Endpoint
HTTP
GET /2023-01-01/connections
Response example
JSON
{
  "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": "retry",
            "strategy": "linear",
            "count": 10,
            "interval": 60000
          }
        ]
      },
      "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": "retry",
          "strategy": "linear",
          "count": 10,
          "interval": 60000
        }
      ]
    }
  ]
}

Retrieve a connection

This endpoint retrieves a specific connection.

URL Parameter

ParameterDescription
idWebhook ID
Endpoint
HTTP
GET /2023-01-01/connections/:id
Response example
JSON
{
  "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"
      }
    ]
  },
  "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"
    }
  ]
}

Create a connection

This endpoint creates a 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 connection with new resources

You can create a connection's underlying source, destination, and ruleset with a single call by declaring an object for any of those resources.

Create a connection with existing resources

You can reuse a source, destination, or ruleset by referencing their ID.

Endpoint
HTTP
POST /2023-01-01/connections
Request body example
JSON
{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "url": "https://example.com/webhook"
  }
}
Response example
JSON
{
  "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"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    }
  ]
}
Create connection with a new source and destination
JSON
{
  "name": "github-some-api",
  "source": {
    "name": "github"
  },
  "destination": {
    "name": "some-api",
    "url": "https://example.com/webhook"
  }
}
Create a connection reusing a source & destination
JSON
{
  "source_id": "src_xxx",
  "destination_id": "des_xxx"
}

Create/Update a connection

This endpoint creates a connection, or updates an existing connection by name.

A connection's source and destination cannot be updated.

Body Parameters

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

Create/Update a connection with new resources

You can create a connection's underlying source, destination, and ruleset with a single call by declaring an object for any of those resources.

Create/Update a connection with existing resources

You can reuse a source, destination, or ruleset by referencing their ID.

Endpoint
HTTP
PUT /2023-01-01/connections
Request body example
JSON
{
  "name": "shopify-my-api",
  "source": {
    "name": "shopify"
  },
  "destination": {
    "name": "my-api",
    "url": "https://example.com/webhook"
  }
}
Response example
JSON
{
  "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"
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    }
  ]
}

Update a connection

This endpoint updates a 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
Endpoint
HTTP
PUT /2023-01-01/connections/:id
Request body example
JSON
{
  "ruleset_id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ"
}
Response example
JSON
{
  "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": "retry",
        "strategy": "linear",
        "count": 10,
        "interval": 60000
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}

Pause a connection

This endpoint pauses a connection.

A paused connection will still receive events, but those events will be marked with a status of HOLD and will be delivered only once the connection is unpaused.

URL Parameter

ParameterDescription
idConnection ID

The parameter paused_at is set to the current timestamp.

Endpoint
HTTP
PUT /2023-01-01/connections/:id/pause
Response example
JSON
{
  "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": "retry",
        "strategy": "linear",
        "count": 10,
        "interval": 60000
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}

Unpause a connection

This endpoint unpauses a connection.

Any event with a status of HOLD will be attempted (rate limits will be respected). This operation is asynchronous, so it may take some time for all events to be QUEUED for delivery.

URL Parameter

ParameterDescription
idConnection ID

The parameter paused_at is set to null.

Endpoint
HTTP
PUT /2023-01-01/connections/:id/unpause
Response example
JSON
{
  "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": "retry",
        "strategy": "linear",
        "count": 10,
        "interval": 60000
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}

Archive a connection

This endpoint archives a connection.

An 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.

Endpoint
HTTP
PUT /2023-01-01/connections/:id/archive
Response example
JSON
{
  "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": "retry",
        "strategy": "linear",
        "count": 10,
        "interval": 60000
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}

Unarchive a connection

This endpoint unarchives a connection.

The associated source and destination will also be unarchived if they were previously archived.

URL Parameter

ParameterDescription
idConnection ID

The parameter archived_at is set to null.

Endpoint
HTTP
PUT /2023-01-01/connections/:id/unarchive
Response example
JSON
{
  "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": "retry",
        "strategy": "linear",
        "count": 10,
        "interval": 60000
      }
    ]
  },
  "resolved_rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}

Sources

A source represents any third party that sends webhooks to Hookdeck.

Endpoints
HTTP
GET /2023-01-01/sources
GET /2023-01-01/sources/:id
POST /2023-01-01/sources
PUT /2023-01-01/sources
PUT /2023-01-01/sources/:id
PUT /2023-01-01/sources/:id/archive
PUT /2023-01-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_atdateDate the source was last updated
created_atdateDate the source was created

Using the source URL

The source object contains a unique URL that must be supplied to your webhook's provider. Each valid HTTP POST request received at this URL creates an event.

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

This endpoint lists all sources, or a subset of sources.

Query Parameter

ParameterTypeDescription
idstring[]Filter by source IDs
namestringThe source name
archivedbooleanInclude archived resources in the response
archived_atdateDate the source was archived
limitnumberLimit the returned source count (max 250)
Endpoint
HTTP
GET /2023-01-01/sources
Response example
JSON
{
  "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

This endpoint retrieves a specific source.

URL Parameter

ParameterDescription
idSource ID
Endpoint
HTTP
GET /2023-01-01/sources/:id
Response example
JSON
{
  "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
Endpoint
HTTP
POST /2023-01-01/sources
Request body example
JSON
{
  "name": "shopify"
}
Response example
JSON
{
  "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
Endpoint
HTTP
PUT /2023-01-01/sources
Request body example
JSON
{
  "name": "shopify"
}
Response example
JSON
{
  "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 updates a source.

URL Parameter

ParameterDescription
idSource ID

Body Parameters

ParameterTypeDescription
namestringA unique name for the source
Endpoint
HTTP
PUT /2023-01-01/sources/:id
Request body example
JSON
{
  "name": "shopify"
}
Response example
JSON
{
  "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 connections.

URL Parameter

ParameterDescription
idSource ID

The parameter archived_at is set to the current timestamp.

Endpoint
HTTP
PUT /2023-01-01/sources/:id/archive
Response example
JSON
{
  "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

This endpoint unarchives a source.

URL Parameter

ParameterDescription
idSource ID

The parameter archived_at is set to null.

Endpoint
HTTP
PUT /2023-01-01/sources/:id/unarchive
Response example
JSON
{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "archived_at": "null",
  "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"
}

Destinations

A destination is any endpoint to which your webhooks can be routed.

Endpoints
HTTP
GET /2023-01-01/destinations
GET /2023-01-01/destinations/:id
POST /2023-01-01/destinations
PUT /2023-01-01/destinations
PUT /2023-01-01/destinations/:id
PUT /2023-01-01/destinations/:id/archive
PUT /2023-01-01/destinations/:id/unarchive

Destination object

ParameterTypeDefaultDescription
idstringID of the destination
team_idstringID of the workspace
namestringA unique, human-friendly name for the destination
urlurlHTTP endpoint of the destination
cli_pathstringPath for the CLI destination
rate_limitnumberLimit event attempts to receive per period. Max value is workspace plan's max attempts thoughput, as defined here
rate_limit_periodstring'second'Period to rate limit attempts (second, minute or hour)
archived_atdatenullDate the destination was archived
updated_atdateDate the destination was last updated
created_atdateDate the destination was created
JSON
{
  "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

This endpoint lists all destinations, or a subset of destinations.

Query Parameter

ParameterTypeDescription
idstring[]Filter by destination IDs
namestringThe destination name
archivedbooleanInclude archived resources in the 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)
Endpoint
HTTP
GET /2023-01-01/destinations
Response example
JSON
{
  "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

This endpoint retrieves a specific destination.

URL Parameter

ParameterDescription
idDestination ID
Endpoint
HTTP
GET /2023-01-01/destinations/:id
Response example
JSON
{
  "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.

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, minute or hour)

One of url or cli_path is required.

Endpoint
HTTP
POST /2023-01-01/destinations
Request body example
JSON
{
  "name": "my-api",
  "url": "https://example.com/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second"
}
Response example
JSON
{
  "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, minute or hour)
Endpoint
HTTP
PUT /2023-01-01/destinations
Request body example
JSON
{
  "name": "my-api",
  "url": "https://example.com/webhook",
  "rate_limit": 5,
  "rate_limit_period": "second"
}
Response example
JSON
{
  "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, minute or hour)
Endpoint
HTTP
PUT /2023-01-01/destinations/:id
Request body example
JSON
{
  "name": "my-new-api"
}
Response example
JSON
{
  "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.

Endpoint
HTTP
PUT /2023-01-01/destinations/:id/archive
Response example
JSON
{
  "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

This endpoint unarchives a destination.

URL Parameter

ParameterDescription
idDestination ID

The parameter archived_at is set to null.

Endpoint
HTTP
PUT /2023-01-01/destinations/:id/unarchive
Response example
JSON
{
  "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

A ruleset defines a group of rules that can be used across many connections.

Endpoints
HTTP
GET /2023-01-01/rulesets
GET /2023-01-01/rulesets/:id
POST /2023-01-01/rulesets
PUT /2023-01-01/rulesets
PUT /2023-01-01/rulesets/:id
PUT /2023-01-01/rulesets/:id/archive
PUT /2023-01-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_atdateDate the ruleset was last updated
created_atdateDate the ruleset was created
JSON
{
  "id": "rls_5b3mzbxk83c0k89",
  "name": "default-ruleset",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 10800000,
      "strategy": "linear"
    }
  ],
  "is_team_default": true,
  "archived_at": null,
  "updated_at": "2020-03-22T17:45:20.742Z",
  "created_at": "2020-03-22T17:45:20.746Z"
}

Retrieve all rulesets

This endpoint lists all rulesets, or a subset of rulesets.

Query Parameter

ParameterTypeDescription
idstring[]Filter by ruleset IDs
namestringThe ruleset name
archivedbooleanInclude archived resources in the response
archived_atdateDate the ruleset was archived
limitnumberLimit the returned event count (max 250)
Endpoint
HTTP
GET /2023-01-01/rulesets
Response example
JSON
{
  "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": "retry",
          "strategy": "linear",
          "count": 10,
          "interval": 60000
        }
      ]
    }
  ]
}

Retrieve a ruleset

This endpoint retrieves a specific ruleset.

URL Parameter

ParameterDescription
idRuleset ID
Endpoint
HTTP
GET /2023-01-01/rulesets/:id
Response example
JSON
{
  "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": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}

Create a ruleset

This endpoint creates a ruleset.

Body Parameters

ParameterTypeDescription
namestringName for the ruleset
rulesRule[]Array of rules to apply
Endpoint
HTTP
POST /2023-01-01/rulesets
Request body example
JSON
{
  "name": "fast-retry-ruleset",
  "rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}
Response example
JSON
{
  "id": "rls_YreVNPlduZdaCIF1cDf2a11u",
  "name": "fast-retry-ruleset",
  "rules": [
    {
      "type": "retry",
      "count": 10,
      "interval": 60000,
      "strategy": "linear"
    }
  ],
  "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
rulesRule[]Array of rules to apply
Endpoint
HTTP
PUT /2023-01-01/rulesets
Request body example
JSON
{
  "name": "fast-retry-ruleset",
  "rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}
Response example
JSON
{
  "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
rulesRule[]Array of rules to apply
Endpoint
HTTP
PUT /2023-01-01/rulesets/:id
Request body example
JSON
{
  "rules": [
    {
      "type": "retry",
      "strategy": "linear",
      "count": 10,
      "interval": 60000
    }
  ]
}
Response example
JSON
{
  "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.

Endpoint
HTTP
PUT /2023-01-01/rulesets/:id/archive
Response example
JSON
{
  "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

This endpoint unarchives a ruleset.

URL Parameter

ParameterDescription
idRuleset ID

The parameter archived_at is set to null.

Endpoint
HTTP
PUT /2023-01-01/rulesets/:id/unarchive
Response example
JSON
{
  "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"
    }
  ]
}

Issue Triggers

Issue Triggers allow you to configure the rules under which new Issues (and any corresponding notifications) should be opened for the different issue types.

Endpoints
HTTP
GET /2023-01-01/issue-triggers
GET /2023-01-01/issue-triggers/:id
POST /2023-01-01/issue-triggers
PUT /2023-01-01/issue-triggers/:id
PUT /2023-01-01/issue-triggers
POST /2023-01-01/issue-triggers/:id
PUT /2023-01-01/issue-triggers/:id/disable
PUT /2023-01-01/issue-triggers/:id/enable
DELETE /2023-01-01/issue-triggers/:id
GET /2023-01-01/issue-triggers
POST /2023-01-01/issue-triggers
PUT /2023-01-01/issue-triggers/:id
DELETE /2023-01-01/issue-triggers/:id

Issue Trigger Object

ParameterTypeDefaultDescription
idstringID of the issue trigger
team_idstringID of the workspace
typestringIssue type, one of delivery, transformation, backpressure
namestringnullOptional unique name to use as reference when using the API
configsObjectConfiguration object for the specific issue type selected
channelsObjectNotification channels object for the specific channel type
disabled_atstringISO timestamp for when the issue trigger was disabled
updated_atstringISO timestamp for when the issue trigger was last updated
created_atstringISO timestamp for when the issue trigger was created
JSON
{
  "id": "it_oK5SRphjGq3h7A",
  "team_id": "tm_ARMha0tPZIjF",
  "name": null,
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "channels": {
    "slack": {
      "channel_name": "alerts"
    },
    "opsgenie": {},
    "email": {}
  }
  "disabled_at": null,
  "updated_at": "2022-12-16T02:09:17.813Z",
  "created_at": "2022-12-16T02:09:17.812Z"
}

Notification Channel Providers

ParameterTypeParameters
slackobjectchannel_name
opsgenieobject
emailobject

This endpoint lists all issue triggers, or a subset of issue triggers.

Query Parameter

ParameterTypeDescription
idstringFilter by issue trigger IDs
typestringThe issue trigger type
statusstringThe issue status
disabled_atdateDate the issues were opened
order_bystringThe date property to order by
dirstringThe ordering direction
limitnumberLimit the returned model count (max 250)
JSON
{
{
    "slack": {
      "channel_name": "alerts"
    },
    "opsgenie": {},
    "email": {}
  }
}

A workspace integration for each providers must be configured from the dashboard for the notification channels to work. [Workspace integrations](https://dashboard.hookdeck.com/workspace/settings).

**Delivery issue type configs**

| Parameter   | Type                 | Default | Description                                                                                |
| ----------- | -------------------- | ------- | ------------------------------------------------------------------------------------------ |
| connections | `string`, `string[]` |         | A pattern to match on the connection name or array of connection IDs. Use `*` as wildcard. |
| strategy    | `string`             |         | The strategy uses to open the issue, one of `final_attempt` or `first_attempt`             |

**Transformation issue type configs**

| Parameter       | Type                 | Default | Description                                                                                        |
| --------------- | -------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| transformations | `string`, `string[]` |         | A pattern to match on the transformation name or array of transformation IDs. Use `*` as wildcard. |
| log_level       | `string`             |         | The minimum log level to open the issue on, one of `warn`, `error`, `fatal`                        |

**Backpressure issue type configs**

| Parameter    | Type                 | Default | Description                                                                                                |
| ------------ | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| destinations | `string`, `string[]` |         | A pattern to match on the destination name or array of destination IDs. Use `*` as wildcard.               |
| delay        | `number`             |         | The minimum delay (backpressure) to open the issue for min of 1 minute (60000) and max of 1 day (86400000) |

**Wildcard patterns**

| Pattern    | Description |
| ---------- | ----------- |
| `*`        | Match all   |
| `string*`  | Starts with |
| `*string`  | Ends with   |
| `*string*` | Contains    |

### Retrieve all issue triggers

```endpoint
GET /issue-triggers

Retrieve an issue trigger

This endpoint retrieves a specific issue trigger.

URL Parameter

ParameterDescription
idIssue trigger ID
Endpoint
HTTP
GET /2023-01-01/issue-triggers/:id
Response example
JSON
{
  "id": "it_oK5SRphjGq3h7A",
  "team_id": "tm_ARMha0tPZIjF",
  "name": null,
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "disabled_at": null,
  "updated_at": "2022-12-16T02:09:17.813Z",
  "created_at": "2022-12-16T02:09:17.812Z"
}

Create an issue trigger

This endpoint updates an issue trigger.

Body Parameters

ParameterTypeDescription
typestringIssue type, one of delivery, transformation, backpressure
configsObjectConfiguration object for the specific issue type selected
namestringOptional unique name to use as reference when using the API
Endpoint
HTTP
POST /2023-01-01/issue-triggers
Request body example
JSON
{
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  }
}
Response example
JSON
{
  "id": "it_cKj0ANguRIGXGT",
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "team_id": "tm_ARMha0tPZIjF",
  "created_at": "2022-12-16T02:09:51.270Z",
  "name": null,
  "disabled_at": null,
  "updated_at": "2022-12-16T02:09:51.270Z"
}

Update an issue trigger

This endpoint updates an issue trigger.

URL Parameter

ParameterDescription
idIssue trigger ID

Body Parameters

ParameterTypeDescription
typestringIssue type, one of delivery, transformation, backpressure
configsObjectConfiguration object for the specific issue type selected
namestringOptional unique name to use as reference when using the API
Endpoint
HTTP
PUT /2023-01-01/issue-triggers/:id
Request body example
JSON
{
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  }
}
Response example
JSON
{
  "id": "it_BfxyEjSg8WM96S",
  "team_id": "tm_ARMha0tPZIjF",
  "name": null,
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "disabled_at": null,
  "updated_at": "2022-12-16T02:09:51.294Z",
  "created_at": "2022-12-16T02:08:58.244Z"
}

Create or Update an issue trigger

This endpoint creates a issue trigger, or updates an existing issue trigger by name.

Name is required for this endpoint

Body Parameters

ParameterTypeDescription
typestringIssue type, one of delivery, transformation, backpressure
configsObjectConfiguration object for the specific issue type selected
namestringRequired. Unique name to use as reference when using the API
Endpoint
HTTP
PUT /2023-01-01/issue-triggers
Request body example
JSON
{
  "type": "delivery",
  "name": "all-connection",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  }
}
Response example
JSON
{
  "id": "it_BfxyEjSg8WM96S",
  "team_id": "tm_ARMha0tPZIjF",
  "name": "all-connection",
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "disabled_at": null,
  "updated_at": "2022-12-16T02:09:51.294Z",
  "created_at": "2022-12-16T02:08:58.244Z"
}

Delete an issue trigger

This endpoint deletes an issue trigger and all associated issues.

URL Parameter

ParameterDescription
idIssue trigger ID
Endpoint
HTTP
DELETE /2023-01-01/issue-triggers/:id
Response example
JSON
{
  "id": "it_oK5SRphjGq3h7A"
}

Disable an issue trigger

This endpoint disables an issue trigger.

URL Parameter

ParameterDescription
idIssue trigger ID
Endpoint
HTTP
PUT /2023-01-01/issue-triggers/:id/disable
Response example
JSON
{
  "id": "it_oK5SRphjGq3h7A",
  "team_id": "tm_ARMha0tPZIjF",
  "name": null,
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "disabled_at": null,
  "updated_at": "2022-12-16T02:09:51.313Z",
  "created_at": "2022-12-16T02:09:17.812Z"
}

Enable an issue trigger

This endpoint enables an issue trigger.

URL Parameter

ParameterDescription
idIssue trigger ID
Endpoint
HTTP
PUT /2023-01-01/issue-triggers/:id/enable
Response example
JSON
{
  "id": "it_oK5SRphjGq3h7A",
  "team_id": "tm_ARMha0tPZIjF",
  "name": null,
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "disabled_at": "2022-12-16T02:09:51.330Z",
  "updated_at": "2022-12-16T02:09:51.330Z",
  "created_at": "2022-12-16T02:09:17.812Z"
}

Integrations

An integration configures platform-specific behaviors, such as signature verification.

Endpoints
HTTP
GET /2023-01-01/integrations
GET /2023-01-01/integrations/:id
POST /2023-01-01/integrations
PUT /2023-01-01/integrations/:id
DELETE /2023-01-01/integrations/:id
PUT /2023-01-01/integrations/:id/attach/:source_id
PUT /2023-01-01/integrations/:id/deattach/:source_id

Integration object

ParameterTypeDefaultDescription
idstringID of the integration
team_idstringID of the workspace
labelstringLabel of the integration
providerstringThe provider name (see provider list below)
featuresstring[]List of features to enable (see features list below)
configsobjectDecrypted Key/Value object of the associated configuration for that provider
sourcesstring[]List of source IDs the integration is attached to
updated_atdateDate the source was last updated
created_atdateDate the source was created

Providers and features

FeatureBehavior
VERIFICATIONEnable authenticity verification when a request is received by Hookdeck. If the request is not authentic, it will be ignored and not create an event.
HANDSHAKEEnable handshake (or URL validation) for platforms that require it, and use a unique value to perform the handshake.
POLLINGPREVIEW ONLY. Enable automatic polling and reconciliation.
Supported features by provider

Each provider has a set of available features. Additionally, each feature requires a set of Key/Value configuration parameters that need to be defined as part of the configs object.

ProviderFeaturesConfig Keys
twitterHANDSHAKEapi_key
zoomHANDSHAKE, VERIFICATIONwebhook_secret_key
rechargeVERIFICATIONwebhook_secret_key
stripeVERIFICATIONwebhook_secret_key
shopifyVERIFICATIONwebhook_secret_key
shopifyPOLLINGContact us
githubVERIFICATIONwebhook_secret_key
postmarkVERIFICATIONwebhook_secret_key
typeformVERIFICATIONwebhook_secret_key
xeroVERIFICATIONwebhook_secret_key
svixVERIFICATIONwebhook_secret_key
adyenVERIFICATIONwebhook_secret_key
akeneoVERIFICATIONwebhook_secret_key
gitLabVERIFICATIONwebhook_secret_key
property-finderVERIFICATIONwebhook_secret_key
woocommerceVERIFICATIONwebhook_secret_key
Supported features for generic configurations

Generic configurations let you add support for providers that are not explicitly supported.

GenericFeaturesConfig Keys
hmacVERIFICATIONalgorithm, encoding, header_key, webhook_secret_key
basic_authVERIFICATIONname, password
api_keyVERIFICATION
Supported values for generic HMAC keys

The following value types are supported for generic HMAC implementations.

KeySupported values
algorithmsha256, sha512, sha1, md5
encodinghex, base64
JSON
{
  "id": "int_9wnkSCsbk8nPOy",
  "team_id": "tm_AkLVUIfTy4nn",
  "label": "Shopify",
  "provider": "shopify",
  "updated_at": "2022-06-13T13:27:16.822Z",
  "created_at": "2022-06-13T13:27:16.821Z",
  "features": ["VERIFICATION"],
  "sources": [],
  "configs": {
    "webhook_secret_key": "your-secret"
  }
}

Retrieve all integrations

This endpoint lists all integrations.

Query Parameter

ParameterTypeDescription
labelstringThe integration label
providerstringThe integration provider
Endpoint
HTTP
GET /2023-01-01/integrations
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100
  },
  "count": 1,
  "models": [
    {
      "id": "int_9wnkSCsbk8nPOy",
      "team_id": "tm_AkLVUIfTy4nn",
      "label": "Shopify",
      "provider": "shopify",
      "updated_at": "2022-06-13T13:27:16.822Z",
      "created_at": "2022-06-13T13:27:16.821Z",
      "features": [
        "VERIFICATION"
      ],
      "sources": [],
      "configs": {
        "webhook_secret_key": "your-secret"
      }
    }
  ]
}

Retrieve an integration

This endpoint retrieves a specific integration.

URL Parameter

ParameterDescription
idIntegration ID
Endpoint
HTTP
GET /2023-01-01/integrations/:id
Response example
JSON
{
  "id": "int_9wnkSCsbk8nPOy",
  "team_id": "tm_AkLVUIfTy4nn",
  "label": "Shopify",
  "provider": "shopify",
  "updated_at": "2022-06-13T13:27:16.822Z",
  "created_at": "2022-06-13T13:27:16.821Z",
  "features": [
    "VERIFICATION"
  ],
  "sources": [],
  "configs": {
    "webhook_secret_key": "your-secret"
  }
}

Create an integration

This endpoint creates an integration.

Body Parameters

ParameterTypeDefaultDescription
labelstringLabel of the integration
providerstringThe provider name (see provider list above)
featuresstring[]List of features to enable (see features list above)
configsobjectDecrypted Key/Value object of the associated configuration for that provider
Endpoint
HTTP
POST /2023-01-01/integrations
Request body example
JSON
{
  "label": "Shopify",
  "configs": {
    "webhook_secret_key": "your-secret"
  },
  "provider": "shopify",
  "features": [
    "VERIFICATION"
  ]
}
Response example
JSON
{
  "id": "int_XMx4wvW0luLTb4",
  "team_id": "tm_AkLVUIfTy4nn",
  "label": "Shopify",
  "provider": "shopify",
  "updated_at": "2022-06-13T13:28:24.794Z",
  "created_at": "2022-06-13T13:28:24.793Z",
  "features": [
    "VERIFICATION"
  ],
  "sources": [],
  "configs": {
    "webhook_secret_key": "your-secret"
  }
}

Update an integration

This endpoint updates an integration.

Body Parameters

ParameterTypeDefaultDescription
labelstringLabel of the integration
providerstringThe provider name (see provider list above)
featuresstring[]List of features to enable (see features list above)
configsobjectDecrypted Key/Value object of the associated configuration for that provider
Endpoint
HTTP
PUT /2023-01-01/integrations/:id
Request body example
JSON
{
  "configs": {
    "webhook_secret_key": "your-new-secret"
  }
}
Response example
JSON
{
  "id": "int_XMx4wvW0luLTb4",
  "team_id": "tm_AkLVUIfTy4nn",
  "label": "Shopify",
  "provider": "shopify",
  "updated_at": "2022-06-13T13:28:24.794Z",
  "created_at": "2022-06-13T13:28:24.793Z",
  "features": [
    "VERIFICATION"
  ],
  "sources": [],
  "configs": {
    "webhook_secret_key": "your-new-secret"
  }
}

Delete an integration

This endpoint deletes an integration.

URL Parameter

ParameterDescription
idIntegration ID
Endpoint
HTTP
DELETE /2023-01-01/integrations/:id
Response example
JSON
{
  "id": "int_9wnkSCsbk8nPOy"
}

Attach an integration to a source

This endpoint attaches an integration to a source

URL Parameter

ParameterDescription
idIntegration ID
source_idSource ID
Endpoint
HTTP
PUT /2023-01-01/integrations/:id/attach/:source_id
Response example
JSON
{
  "success": true
}

Detatch an integration to a source

This endpoint detaches an integration from a source

URL Parameter

ParameterDescription
idIntegration ID
source_idSource ID
Endpoint
HTTP
PUT /2023-01-01/integrations/:id/detach/:source_id
Response example
JSON
{
  "success": true
}

Transformations

A transformation represents JavaScript code that will be executed on a connection's requests. Transformations are applied to connections using Rules.

Endpoints
HTTP
GET /2023-01-01/transformations
GET /2023-01-01/transformations/:id
POST /2023-01-01/transformations
PUT /2023-01-01/transformations/:id
PUT /2023-01-01/transformations
PUT /2023-01-01/transformations/run
GET /2023-01-01/transformations/:id/executions
GET /2023-01-01/transformations/:id/executions/:execution_id

Transformation Object

ParameterTypeDefaultDescription
idstringID of the transformation
team_idstringID of the workspace
namestringA unique, human-friendly name for the transformation
codestringJavaScript code to be executed
envobjectKey-value environment variables to be passed to the transformation
updated_atdateDate the transformation was last updated
created_atdateDate the transformation was created
JSON
{
  "id": "trs_XRyNGe8sta9SN9",
  "team_id": "tm_Vn0Fn3sEqjGX",
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "updated_at": "2022-09-02T23:41:46.180Z",
  "created_at": "2022-09-02T22:10:03.104Z",
  "env": {
    "FOO": "BAR"
  }
}

Retrieve all transformations

This endpoint lists all transformations

Endpoint
HTTP
GET /2023-01-01/transformations
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1
  },
  "count": 1,
  "models": [
    {
      "id": "trs_XRyNGe8sta9SN9",
      "team_id": "tm_Vn0Fn3sEqjGX",
      "name": "example",
      "code": "addHandler('transform', (request, context) => request);",
      "updated_at": "2022-09-02T23:41:12.298Z",
      "created_at": "2022-09-02T22:10:03.104Z",
      "env": {
        "FOO": "BAR"
      }
    }
  ]
}

Retrieve a transformation

This endpoint retrieves a specific transformation.

URL Parameter

ParameterDescription
idTransformation ID
Endpoint
HTTP
GET /2023-01-01/transformations/:id
Response example
JSON
{
  "id": "trs_XRyNGe8sta9SN9",
  "team_id": "tm_Vn0Fn3sEqjGX",
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "updated_at": "2022-09-02T23:41:12.298Z",
  "created_at": "2022-09-02T22:10:03.104Z",
  "env": {
    "FOO": "BAR"
  }
}

Create a transformation

This endpoint creates a transformation.

Body Parameters

ParameterTypeDescription
namestringA unique, human-friendly name for the transformation
codestringJavaScript code to be executed
envobjectKey-value environment variables to be passed to the transformation
Endpoint
HTTP
POST /2023-01-01/transformations
Request body example
JSON
{
  "name": "example-1",
  "code": "addHandler('transform', (request, context) => request);",
  "env": {
    "FOO": "BAR"
  }
}
Response example
JSON
{
  "id": "trs_fvgc1SeB3m1XnV",
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "team_id": "tm_Vn0Fn3sEqjGX",
  "created_at": "2022-09-02T23:41:46.153Z",
  "updated_at": "2022-09-02T23:41:46.154Z",
  "env": {
    "FOO": "BAR"
  }
}

Create/Update a transformation

This endpoint creates a transformation, or updates an existing transformation by name.

Body Parameters

ParameterTypeDescription
namestringA unique, human-friendly name for the transformation
codestringJavaScript code to be executed
envobjectKey-value environment variables to be passed to the transformation
Endpoint
HTTP
PUT /2023-01-01/transformations
Request body example
JSON
{
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "env": {
    "FOO": "BAR"
  }
}
Response example
JSON
{
  "id": "trs_XRyNGe8sta9SN9",
  "team_id": "tm_Vn0Fn3sEqjGX",
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "updated_at": "2022-09-02T23:41:46.198Z",
  "created_at": "2022-09-02T22:10:03.104Z",
  "env": {
    "FOO": "BAR"
  }
}

Update a transformation

This endpoint updates a transformation.

URL Parameter

ParameterDescription
idTransformation ID

Body Parameters

ParameterTypeDescription
name?stringA unique, human-friendly name for the transformation
code?stringJavaScript code to be executed
env?objectKey-value environment variables to be passed to the transformation
Endpoint
HTTP
PUT /2023-01-01/transformations/:id
Request body example
JSON
{
  "code": "addHandler('transform', (request, context) => request);"
}
Response example
JSON
{
  "id": "trs_XRyNGe8sta9SN9",
  "team_id": "tm_Vn0Fn3sEqjGX",
  "name": "example",
  "code": "addHandler('transform', (request, context) => request);",
  "updated_at": "2022-09-02T23:41:46.180Z",
  "created_at": "2022-09-02T22:10:03.104Z",
  "env": {
    "FOO": "BAR"
  }
}

Test the transformation code

This endpoint allows you to test a transformation input against a request without creating the transformation.

Body Parameters

ParameterTypeDescription
requestobjectRequest input to use for the transformation execution
request.body JSON,string Body of the request
request.headersJSONHeaders of the request
request.parsed_queryJSONJSON representation of the query params
request.querystringString representation of the query params of the request
request.pathstringPath of the request
codestringJavaScript code to be executed
env?objectKey-value environment variables to be passed to the transformation
webhook_id?stringID of the connection to use for the execution context
Endpoint
HTTP
PUT /2023-01-01/transformations/run
Request body example
JSON
{
  "request": {
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "example": true
    },
    "path": "/",
    "query": "",
    "parsed_query": {}
  },
  "code": "addHandler('transform', (request, context) => request);"
}
Response example
JSON
{
  "log_level": "info",
  "console": [],
  "request": {
    "headers": {
      "content-type": "application/json",
      "content-length": "16"
    },
    "body": {
      "example": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  }
}

Retieve all transformation execution logs

This endpoint returns the historical executions of a transformation.

Query Parameters

ParameterTypeDescription
log_levelstringLog level of the execution. One of error, log, warn, info, debug
webhook_idstring ID of the connection the execution was run for
issue_idstringID of the associated issue
created_atstringISO date of the transformation's execution
Endpoint
HTTP
GET /2023-01-01/transformations/:id/executions
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100
  },
  "count": 1,
  "models": [
    {
      "id": "reqt_RdK4HW2ZubL0VKJ6kf",
      "transformation_id": "trs_XRyNGe8sta9SN9",
      "team_id": "tm_Vn0Fn3sEqjGX",
      "webhook_id": "web_AXV0d1vkT3ld",
      "log_level": "info",
      "updated_at": "2022-09-02T23:39:03.207Z",
      "created_at": "2022-09-02T23:39:03.447Z",
      "transformed_event_data_id": "edt_dylroX25Cgh8stJkpCjq",
      "logs": []
    }
  ]
}

Retrieve a transformation execution log

This endpoint returns the execution of a transformation. The properties original_event_data and transformed_event_data will be populated with the input and output request data, respectively.

Endpoint
HTTP
GET /2023-01-01/transformations/:id/executions/:execution_id
Response example
JSON
{
  "id": "reqt_RdK4HW2ZubL0VKJ6kf",
  "transformation_id": "trs_XRyNGe8sta9SN9",
  "updated_at": "2022-09-02T23:39:03.207Z",
  "created_at": "2022-09-02T23:39:03.447Z",
  "webhook_id": "web_AXV0d1vkT3ld",
  "team_id": "tm_Vn0Fn3sEqjGX",
  "logs": [],
  "issue_id": null,
  "log_level": "info",
  "transformed_event_data": {
    "headers": {
      "content-length": "24",
      "content-type": "application/json",
      "postman-token": "adcb7eb8-d2b3-4103-98b6-afef40200b1c",
      "user-agent": "PostmanRuntime/7.29.2",
      "x-hookdeck-original-ip": "172.20.0.1"
    },
    "body": {
      "hello": "world"
    },
    "query": "",
    "path": "/",
    "is_large_payload": false
  },
  "original_event_data": {
    "headers": {
      "content-length": "24",
      "content-type": "application/json",
      "postman-token": "adcb7eb8-d2b3-4103-98b6-afef40200b1c",
      "user-agent": "PostmanRuntime/7.29.2",
      "x-hookdeck-original-ip": "172.20.0.1"
    },
    "body": {
      "hello": "world"
    },
    "query": "",
    "path": "/",
    "is_large_payload": false
  },
  "transformed_event_data_id": "edt_dylroX25Cgh8stJkpCjq",
  "original_event_data_id": "edt_4z2L726GSEyZMUjtHzVu"
}

Notifications

Notifications let your team receive alerts anytime an issue changes.

Webhook Notifications

This endpoint enables or disables webhook notifications for the workspace.

Body Parameters

ParameterTypeDescription
enabledbooleanEnable or disable webhook notifications on the workspace
source_idstringThe Hookdeck Source to send the webhook to
topicsstring[]List of topics to send notifications for

Supported Topics

  • issue.opened
  • issue.updated
  • event.successful
Endpoint
HTTP
PUT /2023-01-01/notifications/webhooks
Response example
JSON
{
  "enabled": true,
  "topics": [
    "issue.opened"
  ],
  "source_id": "src_9YmY0SHklrv6zBQz78cKGwSW"
}

Requests

A request represent a webhook received by Hookdeck.

Endpoints
HTTP
GET /2023-01-01/requests
GET /2023-01-01/requests/:id
POST /2023-01-01/requests/:id/retry
GET /2023-01-01/requests/:id/events
GET /2023-01-01/requests/:id/ignored-events

Request object

ParameterTypeDefaultDescription
idstringID of the request
team_idstringID of the workspace
verifiedbooleanfalseWeither or not the request was verified when received
source_idstringID of the associated source
rejection_causestringnullCause for which the request was rejection and not processed. One of SOURCE_ARCHIVED, NO_WEBHOOK, VERIFICATION_FAILED, UNSUPPORTED_HTTP_METHOD, UNSUPPORTED_CONTENT_TYPE, UNPARSABLE_JSON, PAYLOAD_TOO_LARGE
original_event_data_idstringID of the request data
duplicate_hashstringnullHash of the request data payload used to check for duplicates
duplicate_hitsnumber0Count of duplicate hits found
attemptsnumber0Number of delivery attempts made
ingest_prioritystringNORMALThe priority attributed to the request when received. One of LOW or NORMAL
ingested_atdateThe time the request was originally received
events_countnumber0The count of events created from this request (CLI events not included)
cli_events_countnumber0The count of CLI events created from this request
updated_atdateDate the event was last updated
created_atdateDate the event was created
JSON
{
  "id": "req_M3ltWOSF8G6oMS9GS9XX",
  "team_id": "tm_AkLVUIfTy4nn",
  "verified": false,
  "rejection_cause": null,
  "original_event_data_id": "edt_3DzFKL5UU8TKsXJjgct7",
  "duplicate_hash": null,
  "duplicate_hits": null,
  "ingest_priority": "NORMAL",
  "events_count": 2,
  "cli_events_count": 0,
  "ignored_count": 4,
  "ingested_at": "2022-07-29T13:55:10.238Z",
  "source_id": "src_iEfHpkswbzGW",
  "updated_at": "2022-07-29T13:55:15.369Z",
  "created_at": "2022-07-29T13:55:15.092Z"
}

Retrieve all requests

This endpoint lists all request, or a subset of requests.

Requests are sorted by ingested_at date.

Filtering requests

To filter the list of requests, use only supported operators.

For example, append ?created_at[gte]=2021-10-12&created_at[lte]=2021-10-13 to retrieve requests for that specific 24-hour period.

Requests past your workspace archival window are not returned

Query Parameter

ParameterTypeDescription
idstring[]Filter by requests IDs
rejection_causestring[]Filter by rejection cause
source_idstring[]Filter by source IDs
verifiedbooleanFilter by verification status
bodyJSONURL Encoded string of the JSON to match to the data body
headersJSONURL Encoded string of the JSON to match to the data 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 request count (max 250)
Endpoint
HTTP
GET /2023-01-01/requests
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "req_sE7L2cs1Ftn5nUlb8feF"
  },
  "count": 1,
  "models": [
    {
      "id": "req_sE7L2cs1Ftn5nUlb8feF",
      "team_id": "tm_AkLVUIfTy4nn",
      "verified": false,
      "rejection_cause": null,
      "original_event_data_id": "edt_sUZBRp413JM6OSNJk6qc",
      "duplicate_hash": null,
      "duplicate_hits": null,
      "ingest_priority": "NORMAL",
      "ingested_at": "2022-07-29T13:54:26.514Z",
      "source_id": "src_iEfHpkswbzGW",
      "updated_at": "2022-07-29T13:55:20.360Z",
      "created_at": "2022-07-29T13:55:20.330Z",
      "events_count": 2,
      "cli_events_count": 0,
      "ignored_count": 4
    }
  ]
}

Retrieve a request

This endpoint retrieves a specific request.

The response contains the data object with the properties body, headers, path and query representing the original data for that request.

URL Parameter

ParameterDescription
idRequest ID
Endpoint
HTTP
GET /2023-01-01/requests/:id
Response example
JSON
{
  "id": "req_M3ltWOSF8G6oMS9GS9XX",
  "team_id": "tm_AkLVUIfTy4nn",
  "verified": false,
  "rejection_cause": null,
  "original_event_data_id": "edt_3DzFKL5UU8TKsXJjgct7",
  "duplicate_hash": null,
  "duplicate_hits": null,
  "ingest_priority": "NORMAL",
  "ingested_at": "2022-07-29T13:55:10.238Z",
  "source_id": "src_iEfHpkswbzGW",
  "updated_at": "2022-07-29T13:55:15.369Z",
  "created_at": "2022-07-29T13:55:15.092Z",
  "events_count": 2,
  "cli_events_count": 0,
  "ignored_count": 4,
  "data": {
    "headers": {
      "content-length": "18",
      "content-type": "application/json",
      "postman-token": "56fcfa62-9d0e-450f-a638-474b88f928ea",
      "user-agent": "PostmanRuntime/7.29.2",
      "x-hookdeck-original-ip": "172.18.0.1"
    },
    "body": {
      "example": true
    },
    "query": "",
    "parsed_query": {},
    "path": "/"
  }
}

Retry a request

This endpoint triggers a retry for an eligible request. The response contains the updated request and an array of created events if any were created.

URL Parameter

ParameterDescription
idRequest ID

Body Parameter

ParameterTypeDescription
webhook_idsstring[]Subset of webhook_ids to re-run the event logic on. Useful to retry only specific ignored_events
Endpoint
HTTP
POST /2023-01-01/requests/:id/retry
Response example
JSON
{
  "request": {
    "id": "req_M3ltWOSF8G6oMS9GS9XX",
    "team_id": "tm_AkLVUIfTy4nn",
    "verified": false,
    "rejection_cause": null,
    "original_event_data_id": "edt_3DzFKL5UU8TKsXJjgct7",
    "duplicate_hash": null,
    "duplicate_hits": null,
    "ingest_priority": "NORMAL",
    "ingested_at": "2022-07-29T13:55:10.238Z",
    "source_id": "src_iEfHpkswbzGW",
    "updated_at": "2022-07-29T13:55:15.369Z",
    "created_at": "2022-07-29T13:55:15.092Z",
    "events_count": 1,
    "cli_events_count": 0,
    "ignored_count": 0,
    "data": {
      "headers": {
        "content-length": "18",
        "content-type": "application/json",
        "postman-token": "56fcfa62-9d0e-450f-a638-474b88f928ea",
        "user-agent": "PostmanRuntime/7.29.2",
        "x-hookdeck-original-ip": "172.18.0.1"
      },
      "body": {
        "example": true
      },
      "query": "",
      "parsed_query": {},
      "path": "/"
    }
  },
  "events": [
    {
      "id": "evt_wP4CcyPTYjwndo3R2s",
      "team_id": "tm_AkLVUIfTy4nn",
      "webhook_id": "web_lfMH5m6GpkO1",
      "source_id": "src_iEfHpkswbzGW",
      "destination_id": "des_hBX0AHpP3lji",
      "attempts": 1,
      "response_status": 200,
      "last_attempt_at": "2022-07-29T13:55:16.420Z",
      "next_attempt_at": null,
      "successful_at": "2022-07-29T13:55:16.607Z",
      "updated_at": "2022-07-29T13:55:16.609Z",
      "created_at": "2022-07-29T13:55:15.291Z",
      "status": "SUCCESSFUL",
      "cli_id": null,
      "request_id": "req_M3ltWOSF8G6oMS9GS9XX",
      "event_data_id": "edt_3DzFKL5UU8TKsXJjgct7"
    }
  ]
}

Retrieve request events

This endpoint retries the events associated with a request.

URL Parameter

ParameterDescription
idRequest ID

Params

The supported params are the same to retrieve a list of events found here

Endpoint
HTTP
GET /2023-01-01/requests/:id/events
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100
  },
  "count": 1,
  "models": [
    {
      "id": "evt_wP4CcyPTYjwndo3R2s",
      "team_id": "tm_AkLVUIfTy4nn",
      "webhook_id": "web_lfMH5m6GpkO1",
      "source_id": "src_iEfHpkswbzGW",
      "destination_id": "des_hBX0AHpP3lji",
      "attempts": 1,
      "response_status": 200,
      "last_attempt_at": "2022-07-29T13:55:16.420Z",
      "next_attempt_at": null,
      "successful_at": "2022-07-29T13:55:16.607Z",
      "updated_at": "2022-07-29T13:55:16.609Z",
      "created_at": "2022-07-29T13:55:15.291Z",
      "status": "SUCCESSFUL",
      "cli_id": null,
      "request_id": "req_M3ltWOSF8G6oMS9GS9XX",
      "event_data_id": "edt_3DzFKL5UU8TKsXJjgct7"
    }
  ]
}

Retrieve request ignored events

This endpoint retries the events associated with a request.

URL Parameter

ParameterDescription
idRequest ID

Query Parameter

ParameterTypeDescription
idstring[]Filter by ignored events IDs
limitstringLimit the returned event count (max 250)
Endpoint
HTTP
GET /2023-01-01/requests/:id/ignored_events
Response example
JSON
{
  "pagination": {
    "order_by": "id",
    "dir": "desc",
    "limit": 100
  },
  "count": 3,
  "models": [
    {
      "request_id": "req_M3ltWOSF8G6oMS9GS9XX",
      "team_id": "tm_AkLVUIfTy4nn",
      "ignored_event_cause_id": 1475491804,
      "id": 1475491804,
      "cause": "FILTERED",
      "webhook_id": "web_E2iWnvsY0RQE",
      "meta": [
        "body"
      ]
    },
    {
      "request_id": "req_M3ltWOSF8G6oMS9GS9XX",
      "team_id": "tm_AkLVUIfTy4nn",
      "ignored_event_cause_id": 570221994,
      "id": 570221994,
      "cause": "CLI_DISCONNECTED",
      "webhook_id": "web_Tqy2KliIrX1A",
      "meta": null
    },
    {
      "request_id": "req_M3ltWOSF8G6oMS9GS9XX",
      "team_id": "tm_AkLVUIfTy4nn",
      "ignored_event_cause_id": -1330322110,
      "id": -1330322110,
      "cause": "ARCHIVED",
      "webhook_id": "web_I01KDNgvbS5G",
      "meta": null
    }
  ]
}

Events

An event is any request that Hookdeck receives from a source.

Endpoints
HTTP
GET /2023-01-01/events
GET /2023-01-01/events/:id
POST /2023-01-01/events/:id/retry
PUT /2023-01-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
request_idstringID of the request that created the event
event_data_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_atdatenullDate of the most recently attempted retry
next_attempt_atdatenullDate of the next scheduled retry
sucessful_atdatenullDate of the latest successful attempt
updated_atdateDate the event was last updated
created_atdateDate the event was created
JSON
{
  "id": "evt_5b3mzbxk83deakr",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "webhook_id": "web_5b3mzbxk83dcij0",
  "source_id": "src_5b3mzbxk83dciin",
  "destination_id": "des_5b3mzbxk83dciim",
  "cli_id": null,
  "event_data_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

This endpoint lists all events, or a subset of events.

Filtering events

To filter the list of events, use only supported operators.

For example, append ?created_at[gte]=2021-10-12&created_at[lte]=2021-10-13 to retrieve events for that specific 24-hour period.

Including event data

To retrieve events with their data populated, use the ?include=data query parameter. Be aware that this can lead to very large responses.

Payload data exceeding 2.5 MB won't be returned, and data.body will be set to null. The request path, query and headers are still included.

To distinguish between these large payloads and payloads set to the JSON literal null, leverage headers['content-length'].

Including CLI events

CLI events are excluded from the results by default. To query CLI events, use /events?cli_id[any]=true.

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 data body
headersJSONURL Encoded string of the JSON to match to the data 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
include"data"Include the data object in the event model
limitstringLimit the returned event count (max 250)
order_bystringSort by created_at (default) or last_attempt_at.
Endpoint
HTTP
GET /2023-01-01/events
Response example
JSON
{
  "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_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
      "cli_id": null
    }
  ]
}

Retrieve an event

This endpoint retrieves a specific event.

The response contains the data object with the properties body and headers, representing the original data for that webhook request.

URL Parameter

ParameterDescription
idEvent ID
Endpoint
HTTP
GET /2023-01-01/events/:id
Response example
JSON
{
  "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_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "cli_id": null,
  "data": {
    "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
Endpoint
HTTP
POST /2023-01-01/events/:id/retry
Response example
JSON
{
  "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_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
    "cli_id": null,
    "data": {
      "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

The parameter next_attempt_at is set to null. This action is not reversible.

Endpoint
HTTP
PUT /2023-01-01/events/:id/mute
Response example
JSON
{
  "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_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "cli_id": null,
  "data": {
    "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

An attempt is any request that Hookdeck makes on behalf of an event.

Endpoints
HTTP
GET /2023-01-01/attempts
GET /2023-01-01/attempts/:id

Attempt object

ParameterTypeDefaultDescription
idstringAttempt ID
team_idstringTeam ID
event_idstringEvent ID
response_statusnumbernullAttempt's HTTP response code
successful_atdatenullDate the attempt was successful
updated_atdateDate the attempt was last updated
created_atdateDate the attempt was created
error_codestringAttempt could not complete because of an error
bulk_retry_idstringnullID of associated bulk retry
statusstringAttempt status, one of PENDING, FAILED, SUCCESSFUL, QUEUED, HOLD
triggerstringHow this attempt was triggered, one of INITIAL, MANUAL, BULK_RETRY, UNPAUSE, AUTOMATIC
attempt_numbernumberSequential number of attempts (up to and including this one) made for the associated event
delivered_atdatenullDate the attempt was delivered
responded_atdatenullDate the destination responded to this attempt
delivery_latencynumbernullTime elapsed between attempt initiation and final delivery (in ms)
response_latencynumbernullTime elapsed between attempt initiation and a response from the destination (in ms)
archived_atdatenullDate the attempt was archived
bodystringnullResponse body from the destination
requested_urlstringURL of the destination where delivery was attempted
JSON
{
  "id": "atm_12n4ffxk8adnqqj",
  "team_id": "tm_5b3mzbxk83c0k7i",
  "event_id": "evt_12n4ffxk8admulc",
  "response_status": 200,
  "successful_at": "2022-07-29T21:47:07.152Z",
  "updated_at": "2022-07-29T21:47:07.154Z",
  "created_at": "2022-07-29T21:47:06.816Z",
  "error_code": null,
  "bulk_retry_id": null,
  "status": "SUCCESSFUL",
  "trigger": "INITIAL",
  "attempt_number": 1,
  "delivered_at": "2022-07-29T21:47:07.052Z",
  "responded_at": "2022-07-29T21:47:07.152Z",
  "delivery_latency": 44,
  "response_latency": 100,
  "archived_at": null,
  "body": "Accepted",
  "requested_url": "https://mock.hookdeck.com"
}

Retrieve all attempts

This endpoint lists all attempts, or a subset of attempts.

Query Parameter

ParameterTypeDescription
event_idstring[]Event the attempt is associated with
Endpoint
HTTP
GET /2023-01-01/attempts
Response example
JSON
{
  "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,
      "archived_at": null
    }
  ]
}

Retrieve an attempt

This endpoint retrieves a specific attempt.

When retrieving a completed attempt, the response will contain the body of the destination's response.

URL Parameter

ParameterDescription
idAttempt ID
Endpoint
HTTP
GET /2023-01-01/attempts/:id
Response example
JSON
{
  "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,
  "archived_at": null,
  "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/"
}

Bookmarks

A bookmark lets you conveniently store and replay a specific request.

Endpoints
HTTP
GET /2023-01-01/bookmarks
GET /2023-01-01/bookmarks/:id
POST /2023-01-01/bookmarks
PUT /2023-01-01/bookmarks/:id
POST /2023-01-01/bookmarks/:id/trigger
DELETE /2023-01-01/bookmarks/:id

Bookmark object

ParameterTypeDefaultDescription
idstringID of the bookmark
team_idstringID of the workspace
labelstringDescriptive name of the bookmark
namestringA unique, human-friendly name for the bookmark
webhook_idstringID of the associated connection
event_data_idstringID of the bookmarked event data
last_used_atdatenullDate the bookmark was last manually triggered
updated_atdateDate the bookmark was last updated
created_atdateDate the bookmark was created
JSON
{
  "id": "bmk_zRQrmyGVDOEpPcwPqWjeI0p4",
  "team_id": "tm_yUEO9119dsca8EgUE6qwXdCM",
  "webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q",
  "label": "Product Update – Out of Stock",
  "name": null,
  "event_data_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",
  "data": {
    "headers": {
      "content-type": "text/plain",
      "content-length": "20"
    },
    "body": {
      "example": true
    }
  }
}

Retrieve all bookmarks

This endpoint lists all bookmarks, or a subset of bookmarks.

Query Parameter

ParameterTypeDescription
idstringFilter by bookmark IDs
namestringFilter by bookmark name
webhook_idstringFilter by associated connection ID
event_data_idstringFilter by associated event data ID
labelstringFilter by label
last_used_atdateFilter by last used date
limitnumberLimit the returned event count (max 250)
Endpoint
HTTP
GET /2023-01-01/bookmarks
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1
  },
  "count": 0,
  "models": []
}

Retrieve a bookmark

This endpoint retrieves a specific bookmark.

URL Parameter

ParameterDescription
idBookmark ID
Endpoint
HTTP
GET /2023-01-01/bookmarks/:id
Response example
JSON
{
  "id": "bmk_4RbrZcXNALN6WKUljj92hY08",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "label": "Shopify order",
  "alias": null,
  "event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "last_used_at": null,
  "updated_at": "2021-08-02T13:43:23.518Z",
  "created_at": "2021-08-02T13:43:23.516Z",
  "data": {
    "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

This endpoint creates a bookmark.

Body Parameters

ParameterTypeDescription
labelstringName of the bookmark
alias?stringAlternate alias for the bookmark
webhook_idstringID of the associated connection
event_data_idstringID of the event data to bookmark
Endpoint
HTTP
POST /2023-01-01/bookmarks
Request body example
JSON
{
  "label": "Product Update – Out of Stock",
  "event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp"
}
Response example
JSON
{
  "id": "bmk_pgmwVfQ9faN975poe0kW1Sp4",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "label": "Product Update – Out of Stock",
  "alias": null,
  "event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "last_used_at": null,
  "updated_at": "2021-08-02T14:12:57.521Z",
  "created_at": "2021-08-02T14:12:57.520Z",
  "data": {
    "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_data_idstringID of the event data to bookmark
Endpoint
HTTP
PUT /2023-01-01/bookmarks/:id
Request body example
JSON
{
  "label": "Product Update – Out of Stock",
  "event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp"
}
Response example
JSON
{
  "id": "bmk_4RbrZcXNALN6WKUljj92hY08",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "label": "Product Update – Out of Stock",
  "alias": null,
  "event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
  "last_used_at": null,
  "updated_at": "2021-08-02T14:12:57.545Z",
  "created_at": "2021-08-02T13:43:23.516Z",
  "data": {
    "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

This endpoint uses a bookmark to create events.

Multiple events may be created, depending on the target. HTTP bookmarks will trigger at most one event, whereas CLI bookmarks will generate 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.

Endpoint
HTTP
POST /2023-01-01/bookmarks/:id/trigger
Response example
JSON
[
  {
    "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_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
    "cli_id": null,
    "data": {
      "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

This endpoint deletes a bookmark.

Deleting a bookmark won't affect any events previously trigged by that bookmark.

URL Parameter

ParameterDescription
idBookmark ID
Endpoint
HTTP
DELETE /2023-01-01/bookmarks/:id
Response example
JSON
{
  "id": "bmk_4RbrZcXNALN6WKUljj92hY08"
}

Issues

Issues let you track problems in your workspace and communicate resolution steps with your team.

Endpoints
HTTP
GET /2023-01-01/issues
GET /2023-01-01/issues/count
GET /2023-01-01/issues/:id
PUT /2023-01-01/issues/:id
DELETE /2023-01-01/issues/:id

Issue object

ParameterTypeDefaultDescription
idstringID of the issue
team_idstringID of the workspace
typestringIssue type
statusstringOPENEDCurrent status, one of OPENED, ACKNOWLEDGED, RESOLVED, IGNORED
aggregation_keysObjectThe keys on which the issue is aggregated
referenceObjectID references to the object that opened the issue
last_updated_bystringnullID of the team member who last updated the issue status
first_seen_atstringISO timestamp for when the issue was first opened
last_seen_atstringISO timestamp for when the issue last occured
dismissed_atstringnullISO timestamp for when the issue was dismissed
opened_atstringISO timestamp for when the issue was last opened
updated_atstringISO timestamp for when the issue was last updated
created_atstringISO timestamp for when the issue was created
dataObjectExpanded data of the reference object. Only populated when retrieving a single issue and not a list
JSON
{
  "id": "iss_GKcE4uWThIvClCI56edzJGMf",
  "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
  "type": "delivery",
  "status": "OPENED",
  "aggregation_keys": {
    "error_code": [],
    "webhook_id": ["web_lo8z0VQZREANHxEwGJMUllAS"],
    "response_status": [500]
  },
  "reference": {
    "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
    "attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
  },
  "last_updated_by": null,
  "merged_with": null,
  "first_seen_at": "2022-03-13T16:05:26.856Z",
  "last_seen_at": "2022-03-13T17:38:46.827Z",
  "dismissed_at": null,
  "opened_at": "2022-03-13T16:05:26.856Z",
  "updated_at": "2022-03-13T17:38:46.827Z",
  "created_at": "2022-03-13T16:05:26.856Z",
  "data": {
    "trigger_event": {
      "id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "webhook_id": "web_lo8z0VQZREANHxEwGJMUllAS",
      "source_id": "src_BBgENz5uR6YD5shCaBKawSGw",
      "destination_id": "des_vINhNu8uG4OXHxKrhPwuiK89",
      "attempts": 2,
      "response_status": 422,
      "last_attempt_at": "2022-03-13T16:07:52.171Z",
      "next_attempt_at": null,
      "successful_at": null,
      "updated_at": "2022-03-13T16:07:52.314Z",
      "created_at": "2022-03-13T16:05:26.304Z",
      "status": "FAILED",
      "event_data_id": "evtreq_auxUfCEIVhDwEaQHQnX1qcAy",
      "cli_id": null,
      "request": {
        "headers": {
          "content-length": "20",
          "content-type": "application/json"
        },
        "body": {
          "example": true
        },
        "query": "",
        "parsed_query": {},
        "path": "/"
      }
    },
    "trigger_attempt": {
      "id": "atm_wAIWERIBzHWFTYJykqYPacVA",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
      "response_status": 500,
      "successful_at": null,
      "updated_at": "2022-03-13T16:05:26.749Z",
      "created_at": "2022-03-13T16:05:26.318Z",
      "error_code": null,
      "bulk_retry_id": null,
      "status": "FAILED",
      "trigger": "INITIAL",
      "attempt_number": 1,
      "delivered_at": "2022-03-13T16:05:26.597Z",
      "responded_at": "2022-03-13T16:05:26.747Z",
      "delivery_latency": 279,
      "response_latency": 150,
      "archived_at": null,
      "body": {
        "example": true
      },
      "requested_url": "https://mock.hookdeck.com/?status=random"
    }
  }
}

Retrieve all issues

This endpoint lists all issues, or a subset of issues.

Dismissed issues are filtered out by default.

Query Parameter

ParameterTypeDescription
idstringFilter by issue IDs
typestringThe issue type
statusstringThe issue status
merged_withstringThe issue ID it was merged with
aggregation_keysjsonJSON that will evaluate has a partial match of issue aggregation_keys
created_atdateDate the issues were created
first_seen_atdateDate the issues were first seen
last_seen_atdateDate the issues were last seen
dismissed_atdateDate the issues were dismissed
opened_atdateDate the issues were opened
order_bystringThe date property to order by
dirstringThe ordering direction
limitnumberLimit the returned model count (max 250)
Endpoint
HTTP
GET /2023-01-01/issues
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "iss_GKcE4uWThIvClCI56edzJGMf"
  },
  "count": 1,
  "models": [
    {
      "id": "iss_GKcE4uWThIvClCI56edzJGMf",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "type": "delivery",
      "status": "OPENED",
      "aggregation_keys": {
        "error_code": [],
        "webhook_id": [
          "web_lo8z0VQZREANHxEwGJMUllAS"
        ],
        "response_status": [
          500
        ]
      },
      "reference": {
        "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
        "attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
      },
      "last_updated_by": null,
      "merged_with": null,
      "first_seen_at": "2022-03-13T16:05:26.856Z",
      "last_seen_at": "2022-03-13T17:38:46.827Z",
      "dismissed_at": null,
      "opened_at": "2022-03-13T16:05:26.856Z",
      "updated_at": "2022-03-13T17:38:46.827Z",
      "created_at": "2022-03-13T16:05:26.856Z"
    }
  ]
}

Count issues

This endpoint counts all issues, or a subset of issues.

Dismissed issues are filtered out by default.

Query Parameter

ParameterTypeDescription
idstringFilter by issue IDs
typestringThe issue type
statusstringThe issue status
merged_withstringThe issue ID it was merged with
aggregation_keysjsonJSON that will evaluate has a partial match of issue aggregation_keys
created_atdateDate the issues were created
first_seen_atdateDate the issues were first seen
last_seen_atdateDate the issues were last seen
dismissed_atdateDate the issues were dismissed
opened_atdateDate the issues were opened
order_bystringThe date property to order by
dirstringThe ordering direction
limitnumberLimit the returned model count (max 250)
Endpoint
HTTP
GET /2023-01-01/issues/count
Response example
JSON
{
  "count": 10
}

Retrieve an issue

This endpoint retrieves a specific issue.

URL Parameter

ParameterDescription
idIssue ID
Endpoint
HTTP
GET /2023-01-01/issues/:id
Response example
JSON
{
  "id": "iss_GKcE4uWThIvClCI56edzJGMf",
  "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
  "type": "delivery",
  "status": "OPENED",
  "aggregation_keys": {
    "error_code": [],
    "webhook_id": [
      "web_lo8z0VQZREANHxEwGJMUllAS"
    ],
    "response_status": [
      500
    ]
  },
  "reference": {
    "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
    "attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
  },
  "last_updated_by": null,
  "merged_with": null,
  "first_seen_at": "2022-03-13T16:05:26.856Z",
  "last_seen_at": "2022-03-13T17:38:46.827Z",
  "dismissed_at": null,
  "opened_at": "2022-03-13T16:05:26.856Z",
  "updated_at": "2022-03-13T17:38:46.827Z",
  "created_at": "2022-03-13T16:05:26.856Z",
  "data": {
    "trigger_event": {
      "id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "webhook_id": "web_lo8z0VQZREANHxEwGJMUllAS",
      "source_id": "src_BBgENz5uR6YD5shCaBKawSGw",
      "destination_id": "des_vINhNu8uG4OXHxKrhPwuiK89",
      "attempts": 2,
      "response_status": 422,
      "last_attempt_at": "2022-03-13T16:07:52.171Z",
      "next_attempt_at": null,
      "successful_at": null,
      "updated_at": "2022-03-13T16:07:52.314Z",
      "created_at": "2022-03-13T16:05:26.304Z",
      "status": "FAILED",
      "event_data_id": "evtreq_auxUfCEIVhDwEaQHQnX1qcAy",
      "cli_id": null,
      "request": {
        "headers": {
          "content-length": "20",
          "content-type": "application/json"
        },
        "body": {
          "example": true
        },
        "query": "",
        "parsed_query": {},
        "path": "/"
      }
    },
    "trigger_attempt": {
      "id": "atm_wAIWERIBzHWFTYJykqYPacVA",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
      "response_status": 500,
      "successful_at": null,
      "updated_at": "2022-03-13T16:05:26.749Z",
      "created_at": "2022-03-13T16:05:26.318Z",
      "error_code": null,
      "bulk_retry_id": null,
      "status": "FAILED",
      "trigger": "INITIAL",
      "attempt_number": 1,
      "delivered_at": "2022-03-13T16:05:26.597Z",
      "responded_at": "2022-03-13T16:05:26.747Z",
      "delivery_latency": 279,
      "response_latency": 150,
      "archived_at": null,
      "body": {
        "example": true
      },
      "requested_url": "https://mock.hookdeck.com/?status=random"
    }
  }
}

Update an issue

This endpoint updates an issue's status.

URL Parameter

ParameterDescription
idIssue ID

Body Parameters

ParameterTypeDescription
statusstringThe new issue status
Endpoint
HTTP
PUT /2023-01-01/issues/:id
Request body example
JSON
{
  "status": "RESOLVED"
}
Response example
JSON
{
  "id": "iss_GKcE4uWThIvClCI56edzJGMf",
  "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
  "type": "delivery",
  "status": "RESOLVED",
  "aggregation_keys": {
    "error_code": [],
    "webhook_id": [
      "web_lo8z0VQZREANHxEwGJMUllAS"
    ],
    "response_status": [
      500
    ]
  },
  "reference": {
    "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
    "attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
  },
  "last_updated_by": "tmem_Mus4DfdnV4kKepu6W0PKGYMR",
  "merged_with": null,
  "first_seen_at": "2022-03-13T16:05:26.856Z",
  "last_seen_at": "2022-03-13T17:38:46.827Z",
  "dismissed_at": null,
  "opened_at": "2022-03-13T16:05:26.856Z",
  "updated_at": "2022-03-13T17:38:46.827Z",
  "created_at": "2022-03-13T16:05:26.856Z",
  "data": {
    "trigger_event": {
      "id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "webhook_id": "web_lo8z0VQZREANHxEwGJMUllAS",
      "source_id": "src_BBgENz5uR6YD5shCaBKawSGw",
      "destination_id": "des_vINhNu8uG4OXHxKrhPwuiK89",
      "attempts": 2,
      "response_status": 422,
      "last_attempt_at": "2022-03-13T16:07:52.171Z",
      "next_attempt_at": null,
      "successful_at": null,
      "updated_at": "2022-03-13T16:07:52.314Z",
      "created_at": "2022-03-13T16:05:26.304Z",
      "status": "FAILED",
      "event_data_id": "evtreq_auxUfCEIVhDwEaQHQnX1qcAy",
      "cli_id": null,
      "request": {
        "headers": {
          "content-length": "20",
          "content-type": "application/json"
        },
        "body": {
          "example": true
        },
        "query": "",
        "parsed_query": {},
        "path": "/"
      }
    },
    "trigger_attempt": {
      "id": "atm_wAIWERIBzHWFTYJykqYPacVA",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
      "response_status": 500,
      "successful_at": null,
      "updated_at": "2022-03-13T16:05:26.749Z",
      "created_at": "2022-03-13T16:05:26.318Z",
      "error_code": null,
      "bulk_retry_id": null,
      "status": "FAILED",
      "trigger": "INITIAL",
      "attempt_number": 1,
      "delivered_at": "2022-03-13T16:05:26.597Z",
      "responded_at": "2022-03-13T16:05:26.747Z",
      "delivery_latency": 279,
      "response_latency": 150,
      "archived_at": null,
      "body": {
        "example": true
      },
      "requested_url": "https://mock.hookdeck.com/?status=random"
    }
  }
}

Dismiss an issue

This endpoint marks an issue as dismissed.

URL Parameter

ParameterDescription
idIssue ID

The parameter dimissed_at is set to the current timestamp.

Endpoint
HTTP
DELETE /2023-01-01/issues/:id
Response example
JSON
{
  "id": "iss_GKcE4uWThIvClCI56edzJGMf",
  "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
  "type": "delivery",
  "status": "RESOLVED",
  "aggregation_keys": {
    "error_code": [],
    "webhook_id": [
      "web_lo8z0VQZREANHxEwGJMUllAS"
    ],
    "response_status": [
      500
    ]
  },
  "reference": {
    "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
    "attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
  },
  "last_updated_by": "tmem_Mus4DfdnV4kKepu6W0PKGYMR",
  "merged_with": null,
  "first_seen_at": "2022-03-13T16:05:26.856Z",
  "last_seen_at": "2022-03-13T17:38:46.827Z",
  "dismissed_at": "2022-03-15T16:05:26.856Z",
  "opened_at": "2022-03-13T16:05:26.856Z",
  "updated_at": "2022-03-13T17:38:46.827Z",
  "created_at": "2022-03-13T16:05:26.856Z",
  "data": {
    "trigger_event": {
      "id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "webhook_id": "web_lo8z0VQZREANHxEwGJMUllAS",
      "source_id": "src_BBgENz5uR6YD5shCaBKawSGw",
      "destination_id": "des_vINhNu8uG4OXHxKrhPwuiK89",
      "attempts": 2,
      "response_status": 422,
      "last_attempt_at": "2022-03-13T16:07:52.171Z",
      "next_attempt_at": null,
      "successful_at": null,
      "updated_at": "2022-03-13T16:07:52.314Z",
      "created_at": "2022-03-13T16:05:26.304Z",
      "status": "FAILED",
      "event_data_id": "evtreq_auxUfCEIVhDwEaQHQnX1qcAy",
      "cli_id": null,
      "request": {
        "headers": {
          "content-length": "20",
          "content-type": "application/json"
        },
        "body": {
          "example": true
        },
        "query": "",
        "parsed_query": {},
        "path": "/"
      }
    },
    "trigger_attempt": {
      "id": "atm_wAIWERIBzHWFTYJykqYPacVA",
      "team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
      "event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
      "response_status": 500,
      "successful_at": null,
      "updated_at": "2022-03-13T16:05:26.749Z",
      "created_at": "2022-03-13T16:05:26.318Z",
      "error_code": null,
      "bulk_retry_id": null,
      "status": "FAILED",
      "trigger": "INITIAL",
      "attempt_number": 1,
      "delivered_at": "2022-03-13T16:05:26.597Z",
      "responded_at": "2022-03-13T16:05:26.747Z",
      "delivery_latency": 279,
      "response_latency": 150,
      "archived_at": null,
      "body": {
        "example": true
      },
      "requested_url": "https://mock.hookdeck.com/?status=random"
    }
  }
}

Bulk retry events

Endpoints
HTTP
GET /2023-01-01/bulk/events/retry
GET /2023-01-01/bulk/events/retry/:id
POST /2023-01-01/bulk/events/retry/:id/cancel
POST /2023-01-01/bulk/events/retry
GET /2023-01-01/bulk/events/retry/plan/generate

Bulk retry object

JSON
{
  "id": "blkr_SbhWYp1gdsbkno",
  "team_id": "tm_PCQ7f4DjfLLh",
  "query": {
    "dir": "desc",
    "limit": 250,
    "status": ["SUCCESSFUL"],
    "order_by": "created_at",
    "created_at": {
      "gte": "2022-05-02T02:30:00.000Z",
      "lte": "2022-05-03T02:29:59.999Z"
    }
  },
  "updated_at": "2022-05-02T15:24:51.871Z",
  "created_at": "2022-05-02T15:24:51.871Z",
  "completed_at": "2022-05-02T15:27:51.871Z",
  "cancelled_at": null,
  "estimated_batch": 5,
  "processed_batch": 5,
  "estimated_count": 1240,
  "completed_count": 1240,
  "failed_count": 0,
  "progress": 1,
  "in_progress": false
}
ParameterTypeDescription
idstringID of the bulk retry
team_idstringID of the workspace
queryJSONQuery object to filter records
updated_atdateLast time the bulk retry was updated
created_atdateDate the bulk retry was created
completed_atdateDate the bulk retry was completed
cancelled_atdateDate the bulk retry was cancelled
estimated_batchnumberNumber of batches required to complete the bulk retry
processed_batchnumberNumber of batches currently processed
estimated_countnumberNumber of estimated events to be retried
completed_countnumberNumber of events that were successfully delivered
failed_countnumberNumber of events that failed to be delivered
progressnumberProgression of the batch operations, values 0 - 1
in_progressbooleanIndicates if the bulk retry is currently in progress

Retrieve all events bulk retries

This endpoint lists all bulk retries, or a subset of bulk retries.

Query Parameter

ParameterTypeDescription
idstringFilter by bulk retry IDs
queryJSONFilter for events to be included in the bulk retry, use query parameters of Event
query_partial_matchbooleanAllow partial filter match on query property
cancelled_atdateFilter by date the bulk retry was cancelled
completed_atdateFilter by date the bulk retry completed
created_atdateFilter by date the bulk retry was created
in_progressbooleanIndicates if the bulk retry is currently in progress
limitnumberLimit the returned count (max 250)
Endpoint
HTTP
GET /2023-01-01/bulk/events/retry
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "blkret_95Vz4fYjIn5wgatOqX0kLRTH"
  },
  "count": 1,
  "models": [
    {
      "id": "blkr_6dxoWIomd8DQdH",
      "team_id": "tm_UkFg3CHYN50M",
      "query": {
        "status": [
          "SUCCESSFUL"
        ]
      },
      "updated_at": "2022-05-13T09:06:03.983Z",
      "created_at": "2022-05-13T09:05:55.394Z",
      "completed_at": null,
      "cancelled_at": "2022-05-13T09:06:03.982Z",
      "estimated_batch": 4,
      "processed_batch": 2,
      "estimated_count": 28,
      "completed_count": 8,
      "failed_count": 0,
      "number": 15,
      "in_progress": false,
      "progress": 0.29
    }
  ]
}

Retrieve a events bulk retry

This endpoint retrieves a specific bulk retry.

URL Parameter

ParameterDescription
idBulk retry ID
Endpoint
HTTP
GET /2023-01-01/bulk/events/retry/:id
Response example
JSON
{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "status": [
      "SUCCESSFUL"
    ]
  },
  "updated_at": "2022-05-13T09:06:03.983Z",
  "created_at": "2022-05-13T09:05:55.394Z",
  "completed_at": null,
  "cancelled_at": "2022-05-13T09:06:03.982Z",
  "estimated_batch": 4,
  "processed_batch": 2,
  "estimated_count": 28,
  "completed_count": 8,
  "failed_count": 0,
  "number": 15,
  "in_progress": false,
  "progress": 0.29
}

Generate a events bulk retry plan

This endpoint estimates the number of events that will be retried with the given query parameters.

Query Parameter

ParameterTypeDescription
queryJSONFilter by the bulk retry events query object, use query parameters of Event
Endpoint
HTTP
GET /2023-01-01/bulk/events/retry/plan
Response example
JSON
{
  "estimated_count": 301,
  "estimated_batch": 2
}

Create a events bulk retry

This endpoint creates a bulk retry.

Creating a bulk retry automatically begins the operation to retry any events matching the specified filters.

A bulk retry re-attempts delivery for one or more events, based on a filter.

Events on paused connections will still be retried unless excluded from the query.

Body Parameters

ParameterTypeDescription
queryJSONFilter properties for the events to be included in the bulk retry
Endpoint
HTTP
POST /2023-01-01/bulk/events/retry
Request body example
JSON
{
  "query": {
    "source_id": [
      "src_oDhfDrVAZV6OIPdBzcD97of2"
    ]
  }
}
Response example
JSON
{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "source_id": [
      "src_oDhfDrVAZV6OIPdBzcD97of2"
    ]
  },
  "updated_at": "2022-05-13T09:06:03.983Z",
  "created_at": "2022-05-13T09:05:55.394Z",
  "completed_at": null,
  "cancelled_at": "2022-05-13T09:06:03.982Z",
  "estimated_batch": 4,
  "processed_batch": 2,
  "estimated_count": 28,
  "completed_count": 8,
  "failed_count": 0,
  "number": 15,
  "in_progress": false,
  "progress": 0.29
}

Cancel a events bulk retry

This endpoint stops a bulk retry if it's currently running.

URL Parameter

ParameterDescription
idBulk retry ID
Endpoint
HTTP
POST /2023-01-01/bulk/events/retry/:id/cancel
Response example
JSON
{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "status": [
      "SUCCESSFUL"
    ]
  },
  "updated_at": "2022-05-13T09:06:03.983Z",
  "created_at": "2022-05-13T09:05:55.394Z",
  "completed_at": null,
  "cancelled_at": "2022-05-13T09:06:03.982Z",
  "estimated_batch": 4,
  "processed_batch": 2,
  "estimated_count": 28,
  "completed_count": 8,
  "failed_count": 0,
  "number": 15,
  "in_progress": false,
  "progress": 0.29
}

Bulk retry ignored events

Endpoints
HTTP
GET /2023-01-01/bulk/ignored-events/retry
GET /2023-01-01/bulk/ignored-events/retry/:id
POST /2023-01-01/bulk/ignored-events/:id/cancel
POST /2023-01-01/bulk/ignored-events/retry

Bulk retry object

JSON
{
  "id": "blkr_SbhWYp1gdsbkno",
  "team_id": "tm_PCQ7f4DjfLLh",
  "query": {
    "dir": "desc",
    "limit": 250,
    "status": ["SUCCESSFUL"],
    "order_by": "created_at",
    "created_at": {
      "gte": "2022-05-02T02:30:00.000Z",
      "lte": "2022-05-03T02:29:59.999Z"
    }
  },
  "updated_at": "2022-05-02T15:24:51.871Z",
  "created_at": "2022-05-02T15:24:51.871Z",
  "completed_at": "2022-05-02T15:27:51.871Z",
  "cancelled_at": null,
  "estimated_batch": 5,
  "processed_batch": 5,
  "estimated_count": 1240,
  "completed_count": 1240,
  "failed_count": 0,
  "progress": 1,
  "in_progress": false
}
ParameterTypeDescription
idstringID of the bulk retry
team_idstringID of the workspace
queryJSONQuery object to filter records
updated_atdateLast time the bulk retry was updated
created_atdateDate the bulk retry was created
completed_atdateDate the bulk retry was completed
cancelled_atdateDate the bulk retry was cancelled
estimated_batchnumberNumber of batches required to complete the bulk retry
processed_batchnumberNumber of batches currently processed
estimated_countnumberNumber of estimated events to be retried
completed_countnumberNumber of events that were successfully delivered
failed_countnumberNumber of events that failed to be delivered
progressnumberProgression of the batch operations, values 0 - 1
in_progressbooleanIndicates if the bulk retry is currently in progress

Retrieve all ignored events bulk retries

This endpoint lists all bulk retries, or a subset of bulk retries.

Query Parameter

ParameterTypeDescription
idstringFilter by bulk retry IDs
queryJSONFilter for ignored events to be included in the bulk retry, use query parameters of Event
query_partial_matchbooleanAllow partial filter match on query property
cancelled_atdateFilter by date the bulk retry was cancelled
completed_atdateFilter by date the bulk retry completed
created_atdateFilter by date the bulk retry was created
in_progressbooleanIndicates if the bulk retry is currently in progress
limitnumberLimit the returned event count (max 250)
Endpoint
HTTP
GET /2023-01-01/bulk/ignored_events/retry
Response example
JSON
Missing data

Retrieve a ignored events bulk retry

This endpoint retrieves a specific bulk retry.

URL Parameter

ParameterDescription
idBulk retry ID
Endpoint
HTTP
GET /2023-01-01/bulk/ignored-events/retry/:id
Response example
JSON
{
  "id": "bch_sGfZp2fAQWF4Cr",
  "team_id": "tm_Vn0Fn3sEqjGX",
  "query": {
    "cause": [
      "TRANSFORMATION_FAILED"
    ],
    "transformation_id": "trs_fvgc1SeB3m1XnV"
  },
  "updated_at": "2022-09-26T01:12:50.551Z",
  "created_at": "2022-09-26T01:12:50.290Z",
  "completed_at": "2022-09-26T01:12:50.551Z",
  "cancelled_at": null,
  "estimated_batch": 1,
  "estimated_count": 2,
  "processed_batch": 1,
  "completed_count": 2,
  "failed_count": 0,
  "number": 2,
  "in_progress": false,
  "progress": 1
}

Generate a ignored events bulk retry plan

This endpoint estimates the number of events that will be retried with the given query parameters.

Query Parameter

ParameterTypeDescription
queryJSONFilter by the bulk retry ignored event query object
query.cause?stringThe cause of the ignored event
query.webhook_id?stringConnection ID of the ignored event
query.transformation_id?stringThe associated transformation ID (only applicable to the cause TRANSFORMATION_FAILED)
Endpoint
HTTP
GET /2023-01-01/bulk/ignored-events/retry/plan
Response example
JSON
Missing data

Create a ignored events bulk retry

This endpoint creates a bulk retry.

Creating a bulk retry automatically begins the operation to retry any events matching the specified filters.

A bulk retry re-attempts delivery for one or more events, based on a filter.

Events on paused connections will still be retried unless excluded from the query.

Body Parameters

ParameterTypeDescription
queryJSONFilter properties for the events to be included in the bulk retry
Endpoint
HTTP
POST /2023-01-01/bulk/ignored-events/retry
Request body example
JSON
{
  "query": {
    "cause": "TRANSFORMATION_FAILED",
    "transformation_id": "trs_XRyNGe8sta9SN9"
  }
}
Response example
JSON
{
  "id": "bch_YAONJuft9aQ0n3",
  "team_id": "tm_Vn0Fn3sEqjGX",
  "query": {
    "cause": "TRANSFORMATION_FAILED",
    "transformation_id": "trs_XRyNGe8sta9SN9"
  },
  "estimated_batch": 8,
  "estimated_count": 192,
  "completed_count": 0,
  "number": 3,
  "created_at": "2022-09-30T15:00:33.550Z",
  "updated_at": "2022-09-30T15:00:33.551Z",
  "completed_at": null,
  "cancelled_at": null,
  "processed_batch": 0,
  "failed_count": null,
  "in_progress": true,
  "progress": 0
}

Cancel a ignored events bulk retry

This endpoint stops a bulk retry if it's currently running.

URL Parameter

ParameterDescription
idBulk retry ID
Endpoint
HTTP
POST /2023-01-01/bulk/ignored-events/retry/:id/cancel
Response example
JSON
Missing data

Bulk retry requests

Endpoints
HTTP
GET /2023-01-01/bulk/requests/retry
GET /2023-01-01/bulk/requests/retry/:id
POST /2023-01-01/bulk/requests/retry/:id/cancel
POST /2023-01-01/bulk/requests/retry

Bulk retry object

JSON
{
  "id": "blkr_SbhWYp1gdsbkno",
  "team_id": "tm_PCQ7f4DjfLLh",
  "query": {
    "dir": "desc",
    "limit": 250,
    "status": ["SUCCESSFUL"],
    "order_by": "created_at",
    "created_at": {
      "gte": "2022-05-02T02:30:00.000Z",
      "lte": "2022-05-03T02:29:59.999Z"
    }
  },
  "updated_at": "2022-05-02T15:24:51.871Z",
  "created_at": "2022-05-02T15:24:51.871Z",
  "completed_at": "2022-05-02T15:27:51.871Z",
  "cancelled_at": null,
  "estimated_batch": 5,
  "processed_batch": 5,
  "estimated_count": 1240,
  "completed_count": 1240,
  "failed_count": 0,
  "progress": 1,
  "in_progress": false
}
ParameterTypeDescription
idstringID of the bulk retry
team_idstringID of the workspace
queryJSONQuery object to filter records
updated_atdateLast time the bulk retry was updated
created_atdateDate the bulk retry was created
completed_atdateDate the bulk retry was completed
cancelled_atdateDate the bulk retry was cancelled
estimated_batchnumberNumber of batches required to complete the bulk retry
processed_batchnumberNumber of batches currently processed
estimated_countnumberNumber of estimated events to be retried
completed_countnumberNumber of events that were successfully delivered
failed_countnumberNumber of events that failed to be delivered
progressnumberProgression of the batch operations, values 0 - 1
in_progressbooleanIndicates if the bulk retry is currently in progress

Retrieve all requests bulk retries

This endpoint lists all bulk retries, or a subset of bulk retries.

Query Parameter

ParameterTypeDescription
idstringFilter by bulk retry IDs
queryJSONFilter for requests to be included in the bulk retry, use query parameters of Requests
query_partial_matchbooleanAllow partial filter match on query property
cancelled_atdateFilter by date the bulk retry was cancelled
completed_atdateFilter by date the bulk retry completed
created_atdateFilter by date the bulk retry was created
in_progressbooleanIndicates if the bulk retry is currently in progress
limitnumberLimit the returned count (max 250)
Endpoint
HTTP
GET /2023-01-01/bulk/requests/retry
Response example
JSON
{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "blkret_95Vz4fYjIn5wgatOqX0kLRTH"
  },
  "count": 1,
  "models": [
    {
      "id": "blkr_6dxoWIomd8DQdH",
      "team_id": "tm_UkFg3CHYN50M",
      "query": {
        "rejection_cause": [
          "SOURCE_ARCHIVED"
        ]
      },
      "updated_at": "2022-05-13T09:06:03.983Z",
      "created_at": "2022-05-13T09:05:55.394Z",
      "completed_at": null,
      "cancelled_at": "2022-05-13T09:06:03.982Z",
      "estimated_batch": 4,
      "processed_batch": 2,
      "estimated_count": 28,
      "completed_count": 8,
      "failed_count": 0,
      "number": 15,
      "in_progress": false,
      "progress": 0.29
    }
  ]
}

Retrieve a requests bulk retry

This endpoint retrieves a specific bulk retry.

URL Parameter

ParameterDescription
idBulk retry ID
Endpoint
HTTP
GET /2023-01-01/bulk/requests/retry/:id
Response example
JSON
{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "rejection_cause": [
      "SOURCE_ARCHIVED"
    ]
  },
  "updated_at": "2022-05-13T09:06:03.983Z",
  "created_at": "2022-05-13T09:05:55.394Z",
  "completed_at": null,
  "cancelled_at": "2022-05-13T09:06:03.982Z",
  "estimated_batch": 4,
  "processed_batch": 2,
  "estimated_count": 28,
  "completed_count": 8,
  "failed_count": 0,
  "number": 15,
  "in_progress": false,
  "progress": 0.29
}

Generate a requests bulk retry plan

This endpoint estimates the number of events that will be retried with the given query parameters.

Query Parameter

ParameterTypeDescription
queryJSONFilter by the bulk retry events query object, use query parameters of Requests
Endpoint
HTTP
GET /2023-01-01/bulk/requests/retry/plan
Response example
JSON
{
  "estimated_count": 301,
  "estimated_batch": 2
}

Create a requests bulk retry

This endpoint creates a bulk retry.

Creating a bulk retry automatically begins the operation to retry any events matching the specified filters.

Body Parameters

ParameterTypeDescription
queryJSONFilter properties for the events to be included in the bulk retry, use query parameters of Requests
Endpoint
HTTP
POST /2023-01-01/bulk/requests/retry
Request body example
JSON
{
  "query": {
    "source_id": [
      "src_oDhfDrVAZV6OIPdBzcD97of2"
    ]
  }
}
Response example
JSON
{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "rejection_cause": [
      "SOURCE_ARCHIVED"
    ]
  },
  "updated_at": "2022-05-13T09:06:03.983Z",
  "created_at": "2022-05-13T09:05:55.394Z",
  "completed_at": null,
  "cancelled_at": "2022-05-13T09:06:03.982Z",
  "estimated_batch": 4,
  "processed_batch": 2,
  "estimated_count": 28,
  "completed_count": 8,
  "failed_count": 0,
  "number": 15,
  "in_progress": false,
  "progress": 0.29
}

Cancel a requests bulk retry

This endpoint stops a bulk retry if it's currently running.

URL Parameter

ParameterDescription
idBulk retry ID
Endpoint
HTTP
POST /2023-01-01/bulk/requests/retry/:id/cancel
Response example
JSON
{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "rejection_cause": [
      "SOURCE_ARCHIVED"
    ]
  },
  "updated_at": "2022-05-13T09:06:03.983Z",
  "created_at": "2022-05-13T09:05:55.394Z",
  "completed_at": null,
  "cancelled_at": "2022-05-13T09:06:03.982Z",
  "estimated_batch": 4,
  "processed_batch": 2,
  "estimated_count": 28,
  "completed_count": 8,
  "failed_count": 0,
  "number": 15,
  "in_progress": false,
  "progress": 0.29
}

Rule

A rule can be applied to either a Ruleset or a Connection using the rules field.

Retry

The retry rule determines the rate and limit of automatic retries on failed events.

PropertyTypeDescription
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
JSON
{
  "type": "retry",
  "strategy": "linear",
  "count": 5,
  "interval": 60000
}

Delay

The delay rule allows you to introduce a delay between the moment Hookdeck receives an event, and when it's forwarded to your destination.

PropertyTypeDescription
typedelayA delay rule must be of type delay
delaynumberDelay to introduce in MS
JSON
{
  "type": "delay",
  "delay": 1000
}

Filter

The filter rule allows you to permit and route webhooks conditionally based on the contents of their Headers, Body, Query, and/or Path.

For more information on how to set up filters, including syntax, review our filter documentation.

PropertyTypeDescription
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
JSON
{
  "type": "filter",
  "body": {
    "example": true
  }
}

Transform

The transform rule allows you to run arbitrary JavaScript to transform the webhook request.

For more information on how to use transformations, check the transformation documentation.

PropertyTypeDescription
typetransformationA transformation rule must be of type transformation
transformation_id?stringID of the attached transformation object. Optional input, always set once the rule is defined
transformation?ObjectYou can optionally define a new transformation while creating a transform rule
transformation.name?stringThe unique name of the transformation
transformation.code?stringA string representation of your JavaScript (ES6) code to run
transformation.env?Object<string, string>A key-value object of environment variables to encrypt and expose to your transformation code
JSON
{
  "type": "transformation",
  "transformation_id": "trs_XRyNGe8sta9SN9"
}
JSON
{
  "type": "transformation",
  "transformation": {
    "name": "example",
    "code": "addHandler('transform', (request, context) => request)",
    "env": {
      "SECRET": "supersecret"
    }
  }
}

Get In Touch

Reach out using the live chat in the bottom right corner, or our contact form.