REST API Reference

Getting Started

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

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 project settings.

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

Method	Procedure
Bearer Token Authentication	Include the header `Authorization: Bearer $API_KEY`, replacing `$API_KEY` with your personal key
Basic Authentication	Set the username as your API key, and supply an empty password

curl "https://api.hookdeck.com/2024-09-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 events with Hookdeck.

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

Required parameters

Parameter	Type	Description
name	`string`	Name of the new connection
source.name	`string`	Name of the source to create
destination.name	`string`	Name of the destination to create
destination.url	`string`	HTTP endpoint of the destination
destination.cli_path	`string`	Path 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.

POST /connections

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 events from your source.

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

The connection URL is a property of the source object.

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

{
  "id": "web_xxxxxxxxxxxxxxx",
  "source": {
    "url": "https://hkdk.events/xxxxxxxxxxxxxxx",
    [...]
  },
  [...]
}

Authentication

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

Method	Procedure
Bearer Token Authentication	Include the header `Authorization: Bearer $API_KEY`, replacing `$API_KEY` with your project key
Basic Authentication	Set the username as your API key, and supply an empty password

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.

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

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.

Pagination object JSON

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

Get the next page cURL

curl "https://api.hookdeck.com/2024-09-01/connections?next=web_2urj7h9puxk6obro3x"
  -H "Authorization: Basic BASE64_API_TOKEN"

Get the previous page cURL

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

Get the next page without default ordering cURL

curl "https://api.hookdeck.com/2024-09-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.

Parameter	Type	Description
handle	`boolean`	Error was handled by the API and did not resolve in an uncaught exception
status	`integer`	HTTP status code for the error
message	`string`	Any message associated with the error
data	`object`	Any 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.

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 HTTP

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

Operator	Supported Types	Description
gte	`date` `number`	Greater than or equal to
gt	`date` `number`	Greater than
lte	`date` `number`	Lesser than or equal to
lt	`date` `number`	Lesser than
any	`date` `number` `string`	Not `null`
contains	`string`	Contains

Changelog

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

The API version can be set in the base path of any endpoint, such as https://api.hookdeck.com/2024-09-01/sources. Otherwise the API defaults to the oldest supported 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.

Dated versions remain supported for up to 1 year after the date of release. For instance 2023-07-01 will be officially supported until 2024-07-01.

2024-09-01

Change to attempts

Attempts no longer store state and are created when the event is delivered rather then when the event is queued for delivery.

Because of the underlying data structure change, the behavior of the API has changed for some endpoint, regardless of versions. While those are not technically breaking changes, they are worth noting:

The /attempts (see: Retrieve all attempts) endpoint now only returns attempts with status of SUCCESFUL or FAILED. This is true regardless of API version.
The /events/:id/retry will always return null for the attempt property on the response. This is true regardless of API version.

The breaking changes for this version specifically are:

The /events/:id/retry (see: Retry an event) endpoint previously returned { event: Event, attempt: Attempt } and now only returns the Event object in root of the response.

2024-03-01

Renamed archive to disable

On Source, Destination and Connection objects, archive and unarchive have been renamed as disabled and enable. This affects the following:

archived_at has been renamed to disabled_at
/sources/:id/archive have been renamed to /sources/:id/disable (see Disable a source)
/sources/:id/unarchive have been renamed to /sources/:id/enable (see Enable a source)
/connections/:id/archive have been renamed to /connections/:id/disable (see Disable a connection)
/connections/:id/unarchive have been renamed to /connections/:id/enable (see Enable a connection)
/destinations/:id/archive have been renamed to /destinations/:id/disable (see Disable a destination)
/destinations/:id/unarchive have been renamed to /destinations/:id/enable (see Enable a destination)
Ignored event cause ARCHIVED has been renamed as DISABLED
Rejection cause SOURCE_ARCHIVED has been renamed as SOURCE_DISABLED

Standardise source verification configs

To use consistent casing and keys between source authentication and destination authentication, we have made the following changes:

On the Source's verification, rename user as username in the following config types:
- Basic Auth
- Postmark
- Pipedrive
All config types have been uppercased on the Source's verification. For instance, hmac is renamed as HMAC, github is renamed as GITHUB and so on

2023-07-01

Removing rulesets

Removes support for Rulesets and is replaced by setting rules directly on connections.

Removed rulesets object and resolved_rules array from Connections.
Removed all /rulesets endpoints
Removed ruleset and ruleset_id property when creating or updating a Connection

Replacing integrations by Source "verification"

Add the verification property to the Source model
Add the verification input when creating or updating a Source
Remove the integration and integration_id property from Source
Removed all /integrations endpoints

Integrations no longer need to be created and managed independantly from the source it's attached to. Instead you should pass the verification property to the source directly.

2023-01-01

Removed alert rule type from rules on Rulesets and Connections.

2022-11-01 [DEPRECATED]

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 [DEPRECATED]

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 [DEPRECATED]

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

2022-03-01 [DEPRECATED]

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.

2021-08-01 [DEPRECATED]

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

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 [DEPRECATED]

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

OpenAPI Schema

Our OpenAPI schema is available at https://api.hookdeck.com/2024-09-01/openapi.

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.

We provide SDKs for both TypeScript and Go.

Connections

A connection lets you route events from a source to a destination.

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.

Connection object

string

Required

ID of the connection

name

string

Required

Unique name of the connection for this source

full_name

string

Required

Full name of the connection concatenated from source, connection and desitnation name

description

string

Required

Description of the connection

team_id

string

Required

ID of the project

destination

Destination

Required

Associated Destination object

source

Source

Required

Associated Source object

rules

Rule[]

Required

Array of rules configured on the connection

disabled_at

string

Required

Date

Date the connection was disabled

paused_at

string

Required

Date

Date the connection was paused

updated_at

string

Required

Date

Date the connection was last updated

created_at

string

Required

Date

Date the connection was created

Example connection object JSON

{
  "id": "web_mNP60lEYInVfnH1EUWbhfUYL",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear"
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ],
  "destination": {
    "id": "des_6MO6QjY7pOotcDaFZfw2hoWF",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://example.com/webhook",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_at": null,
    "updated_at": "2021-08-02T00:26:46.816Z",
    "created_at": "2021-08-01T21:29:41.788Z",
    "name": "shopify",
    "url": "https://hkdk.events/9YmY0SHklrv6zBQz78cKGwSW"
  }
}

Retrieve all connections

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

Query Parameters

stringstring[]

Filter by connection IDs

name

stringOperatorsstring[]

Filter by connection name

destination_id

stringstring[]

Filter by associated destination IDs

source_id

stringstring[]

Filter by associated source IDs

disabled

boolean

Include disabled resources in the response

disabled_at

stringOperators

Date the connection was disabled

full_name

string

Pattern: ^[a-z0-9-_>\s]+$

Max length: 155

Fuzzy match the concatenated source and connection name. The source name and connection name must be separated by " -> "

paused_at

stringOperators

Date the connection was paused

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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",
      "disabled_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",
        "disabled_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",
        "http_method": "POST",
        "auth_method": {
          "type": "HOOKDECK_SIGNATURE",
          "config": {}
        }
      },
      "source": {
        "id": "src_2Q0cNXCHyzPJCUOmpk76JKeU",
        "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
        "disabled_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 connection

This endpoint retrieves a specific connection.

URL Parameters

string

Required

Connection ID

GET

/2024-09-01/connections/:id

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_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",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Create a connection

This endpoint creates a connection.

Body Parameters

name

string

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique name of the connection for the source

description

string

Max length: 500

Description for the connection

destination_id

string

Max length: 255

ID of a destination to bind to the connection

source_id

string

Max length: 255

ID of a source to bind to the connection

destination

object

Destination input object

source

object

Source input object

rules

Rule[]

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 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 with existing resources

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

Create a connection reusing a source & destination JSON

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

POST

/2024-09-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",
  "disabled_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",
  "destination": {
    "id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "url": "https://example.com/webhook",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_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",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  },
  "rules": []
}

Create/Update a connection

This endpoint creates 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

name

string

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique name of the connection for the source

description

string

Max length: 500

Description for the connection

destination_id

string

Max length: 255

ID of a destination to bind to the connection

source_id

string

Max length: 255

ID of a source to bind to the connection

destination

object

Destination input object

source

object

Source input object

rules

Rule[]

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.

PUT

/2024-09-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",
  "disabled_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",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_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",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Update a connection

This endpoint updates a connection.

URL Parameters

string

Required

Connection ID

Body Parameters

name

string

Pattern: ^[A-z0-9-_]+$

Max length: 155

description

string

Max length: 500

Description for the connection

rules

Rule[]

PUT

/2024-09-01/connections/:id

Request body example JSON

{
  "rules": [
    {
      "type": "retry",
      "count": 5,
      "interval": 3600000,
      "strategy": "linear"
    },
    {
      "body": {
        "type": "customer.subscription.updated"
      },
      "type": "filter"
    }
  ]
}

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_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",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

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 Parameters

string

Required

Connection ID

The parameter paused_at is set to the current timestamp.

PUT

/2024-09-01/connections/:id/pause

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_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",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Unpause a connection

This endpoint unpauses a connection.

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

URL Parameters

string

Required

Connection ID

The parameter paused_at is set to null.

PUT

/2024-09-01/connections/:id/unpause

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_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",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Disable a connection

This endpoint disables a connection. Notice that a connection is enabled by default when created.

An disabled connection will no longer receive or deliver any events.

URL Parameters

string

Required

Connection ID

The parameter disabled_at is set to the current timestamp.

PUT

/2024-09-01/connections/:id/disable

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_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",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Enable a connection

This endpoint enables a connection that has been previously disabled.

The associated source and destination will also be enabled if they were previously disabled.

URL Parameters

string

Required

Connection ID

The parameter disabled_at is set to null.

PUT

/2024-09-01/connections/:id/enable

Response example JSON

{
  "id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
    "disabled_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",
    "http_method": "POST",
    "auth_method": {
      "type": "HOOKDECK_SIGNATURE",
      "config": {}
    }
  },
  "source": {
    "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
    "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
    "disabled_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",
    "allowed_http_methods": [
      "PUT",
      "PATCH",
      "DELETE",
      "POST"
    ],
    "custom_response": null,
    "verification": null
  }
}

Delete a connection

This endpoint permanently deletes a connection.

URL Parameters

string

Required

This action cannot be undone.

Sources

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

Source object

string

Required

ID of the source

name

string

Required

Name for the source

description

string

Description of the source

team_id

string

Required

ID of the project

url

string

Required

URL

A unique URL that must be supplied to your webhook's provider

verification

VerificationConfig

The verification configs for the specified verification type

allowed_http_methods

SourceAllowedHTTPMethod

List of allowed HTTP methods. Defaults to PUT, POST, PATCH, DELETE.

custom_response

SourceCustomResponse

Custom response object

disabled_at

string

Required

Date

Date the source was disabled

updated_at

string

Required

Date

Date the source was last updated

created_at

string

Required

Date

Date the source was created

Using the source URL

The source object contains a unique URL that must be supplied to your provider. Each valid HTTP request received at this URL creates a request.

Example destination object 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",
  "disabled_at": null,
  "updated_at": "2020-03-26T17:15:31.079Z",
  "created_at": "2020-03-22T18:22:38.015Z"
}

Retrieve all sources

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

Query Parameters

stringstring[]

Filter by source IDs

name

stringOperatorsstring[]

The source name

disabled

boolean

Include disabled resources in the response

disabled_at

stringOperators

Date the source was disabled

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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",
      "disabled_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",
      "allowed_http_methods": [
        "PUT",
        "PATCH",
        "DELETE",
        "POST"
      ],
      "custom_response": null,
      "verification": null
    }
  ]
}

Retrieve a source

This endpoint retrieves a specific source.

URL Parameters

string

Required

Source ID

Query Parameters

include

string

Allowed value

verification.configs

GET

/2024-09-01/sources/:id

Response example JSON

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
  "allowed_http_methods": [
    "PUT",
    "PATCH",
    "DELETE",
    "POST"
  ],
  "custom_response": null,
  "verification": null
}

Create a source

This endpoint creates a source.

Body Parameters

name

string

Required

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique name for the source

description

string

Max length: 500

Description for the source

allowed_http_methods

SourceAllowedHTTPMethod

List of allowed HTTP methods. Defaults to PUT, POST, PATCH, DELETE.

custom_response

SourceCustomResponse

Custom response object

verification

VerificationConfig

The verification configs for the specified verification type

POST

/2024-09-01/sources

Request body example JSON

{
  "name": "shopify"
}

Response example JSON

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
  "allowed_http_methods": [
    "PUT",
    "PATCH",
    "DELETE",
    "POST"
  ],
  "custom_response": null,
  "verification": null
}

Create/Update a source

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

Body Parameters

name

string

Required

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique name for the source

description

string

Max length: 500

Description for the source

allowed_http_methods

SourceAllowedHTTPMethod

List of allowed HTTP methods. Defaults to PUT, POST, PATCH, DELETE.

custom_response

SourceCustomResponse

Custom response object

verification

VerificationConfig

The verification configs for the specified verification type

PUT

/2024-09-01/sources

Request body example JSON

{
  "name": "shopify"
}

Response example JSON

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
  "allowed_http_methods": [
    "PUT",
    "PATCH",
    "DELETE",
    "POST"
  ],
  "custom_response": null,
  "verification": null
}

Update a source

This endpoint updates a source.

URL Parameters

string

Required

Source ID

Body Parameters

name

string

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique name for the source

description

string

Max length: 500

Description for the source

allowed_http_methods

SourceAllowedHTTPMethod

List of allowed HTTP methods. Defaults to PUT, POST, PATCH, DELETE.

custom_response

SourceCustomResponse

Custom response object

verification

VerificationConfig

The verification configs for the specified verification type

PUT

/2024-09-01/sources/:id

Request body example JSON

{
  "name": "shopify"
}

Response example JSON

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
  "allowed_http_methods": [
    "PUT",
    "PATCH",
    "DELETE",
    "POST"
  ],
  "custom_response": null,
  "verification": null
}

Disable a source

This endpoint disabled a source and any associated connections.

URL Parameters

string

Required

Source ID

The parameter disabled_at is set to the current timestamp.

PUT

/2024-09-01/sources/:id/disable

Response example JSON

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
  "allowed_http_methods": [
    "PUT",
    "PATCH",
    "DELETE",
    "POST"
  ],
  "custom_response": null,
  "verification": null
}

Enable a source

This endpoint enables a source that has been previously disabled. Sources are enabled by default when created.

URL Parameters

string

Required

Source ID

The parameter disabled_at is set to null.

PUT

/2024-09-01/sources/:id/enable

Response example JSON

{
  "id": "src_9YmY0SHklrv6zBQz78cKGwSW",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "disabled_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",
  "allowed_http_methods": [
    "PUT",
    "PATCH",
    "DELETE",
    "POST"
  ],
  "custom_response": null,
  "verification": null
}

Delete a source

This endpoint permanently deletes a source.

URL Parameters

string

Required

This action cannot be undone. Hookdeck will return HTTP 410 for any new request to that Source URL.

Destinations

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

Destination object

string

Required

ID of the destination

name

string

Required

A unique, human-friendly name for the destination

description

string

Description of the destination

team_id

string

Required

ID of the project

path_forwarding_disabled

boolean

url

string

URL

HTTP endpoint of the destination

cli_path

string

Path for the CLI destination

rate_limit

integer

Limit of events to receive per period. Refered as Delivery Rate limit in the dashboard and documentation.

rate_limit_period

DestinationRateLimitPeriod

Period to rate limit events by. Refered as Delivery Rate period in the dashboard and documentation.

Allowed values

secondminutehourconcurrent

http_method

DestinationHTTPMethod

HTTP method used on requests sent to the destination, overrides the method used on requests sent to the source.

Allowed values

GETPOSTPUTPATCHDELETE

auth_method

DestinationAuthMethodConfig

Config for the destination's auth method

disabled_at

string

Required

Date

Date the destination was disabled

updated_at

string

Required

Date

Date the destination was last updated

created_at

string

Required

Date

Date the destination was created

Example destination object 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",
  "disabled_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 Parameters

stringstring[]

Filter by destination IDs

name

stringOperatorsstring[]

The destination name

disabled

boolean

Include disabled resources in the response

disabled_at

stringOperators

Date the destination was disabled

url

stringstring[]

HTTP endpoint of the destination

cli_path

stringobjectstring[]

Path for the CLI destination

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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",
      "disabled_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",
      "http_method": "POST",
      "auth_method": {
        "type": "HOOKDECK_SIGNATURE",
        "config": {}
      }
    }
  ]
}

Retrieve a destination

This endpoint retrieves a specific destination.

URL Parameters

string

Required

Destination ID

GET

/2024-09-01/destinations/:id

Response example JSON

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://mock.hookdeck.com",
  "disabled_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",
  "http_method": "POST",
  "auth_method": {
    "type": "HOOKDECK_SIGNATURE",
    "config": {}
  }
}

Create a destination

This endpoint creates a destination.

Body Parameters

name

string

Required

Pattern: ^[A-z0-9-_]+$

Max length: 155

Name for the destination

description

string

Max length: 500

Description for the destination

url

string

URL

Endpoint of the destination

cli_path

string

Path for the CLI destination

rate_limit

integer

Limit of events to receive per period. Refered as Delivery Rate limit in the dashboard and documentation.

rate_limit_period

string

Period to rate limit events by. Refered as Delivery Rate period in the dashboard and documentation.

Allowed values

secondminutehourconcurrent

http_method

DestinationHTTPMethod

HTTP method used on requests sent to the destination, overrides the method used on requests sent to the source.

Allowed values

GETPOSTPUTPATCHDELETE

auth_method

DestinationAuthMethodConfig

Config for the destination's auth method

path_forwarding_disabled

boolean

One of url or cli_path is required.

POST

/2024-09-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",
  "disabled_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",
  "http_method": "POST",
  "auth_method": {
    "type": "HOOKDECK_SIGNATURE",
    "config": {}
  }
}

Create/Update a destination

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

Body Parameters

name

string

Required

Pattern: ^[A-z0-9-_]+$

Max length: 155

Name for the destination

description

string

Max length: 500

Description for the destination

url

string

URL

Endpoint of the destination

cli_path

string

Path for the CLI destination

rate_limit

integer

Limit of events to receive per period. Refered as Delivery Rate limit in the dashboard and documentation.

rate_limit_period

string

Period to rate limit events by. Refered as Delivery Rate period in the dashboard and documentation.

Allowed values

secondminutehourconcurrent

http_method

DestinationHTTPMethod

HTTP method used on requests sent to the destination, overrides the method used on requests sent to the source.

Allowed values

GETPOSTPUTPATCHDELETE

auth_method

DestinationAuthMethodConfig

Config for the destination's auth method

path_forwarding_disabled

boolean

PUT

/2024-09-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",
  "disabled_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 Parameters

string

Required

Destination ID

Body Parameters

name

string

Pattern: ^[A-z0-9-_]+$

Max length: 155

Name for the destination

description

string

Max length: 500

Description for the destination

url

string

URL

Endpoint of the destination

cli_path

string

Path for the CLI destination

rate_limit

integer

Limit of events to receive per period. Refered as Delivery Rate limit in the dashboard and documentation.

rate_limit_period

string

Period to rate limit events by. Refered as Delivery Rate period in the dashboard and documentation.

Allowed values

secondminutehourconcurrent

http_method

DestinationHTTPMethod

HTTP method used on requests sent to the destination, overrides the method used on requests sent to the source.

Allowed values

GETPOSTPUTPATCHDELETE

auth_method

DestinationAuthMethodConfig

Config for the destination's auth method

path_forwarding_disabled

boolean

PUT

/2024-09-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",
  "disabled_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",
  "http_method": "POST",
  "auth_method": {
    "type": "HOOKDECK_SIGNATURE",
    "config": {}
  }
}

Disable a destination

This endpoint disables a destination. Notice that a destination is created enabled by default.

URL Parameters

string

Required

Destination ID

The parameter disabled_at is set to the current timestamp.

PUT

/2024-09-01/destinations/:id/disable

Response example JSON

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://mock.hookdeck.com",
  "disabled_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",
  "http_method": "POST",
  "auth_method": {
    "type": "HOOKDECK_SIGNATURE",
    "config": {}
  }
}

Enable a destination

This endpoint enables a destination that has been previously disabled.

URL Parameters

string

Required

Destination ID

The parameter disabled_at is set to null.

PUT

/2024-09-01/destinations/:id/enable

Response example JSON

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "url": "https://mock.hookdeck.com",
  "disabled_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",
  "http_method": "POST",
  "auth_method": {
    "type": "HOOKDECK_SIGNATURE",
    "config": {}
  }
}

Delete a destination

This endpoint permanently deletes a destination.

URL Parameters

string

Required

This action cannot be undone.

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.

Issue Trigger Object

string

Required

ID of the issue trigger

team_id

string

ID of the project

name

string

Optional unique name to use as reference when using the API

type

IssueType

Required

Issue type

Allowed values

deliverytransformationbackpressure

configs

IssueTriggerReference

Required

Configuration object for the specific issue type selected

channels

IssueTriggerChannels

Notification channels object for the specific channel type

disabled_at

string

Date

ISO timestamp for when the issue trigger was disabled

updated_at

string

Required

Date

ISO timestamp for when the issue trigger was last updated

created_at

string

Required

Date

ISO timestamp for when the issue trigger was created

deleted_at

string

Date

ISO timestamp for when the issue trigger was deleted

Example issue trigger object 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

slack

object

Slack channel for an issue trigger

opsgenie

object

Integration channel for an issue trigger

object

Email channel for an issue trigger

A project integration for each providers must be configured from the dashboard for the notification channels to work. Project integrations.

Delivery issue type configs

strategy

IssueTriggerStrategy

Required

The strategy uses to open the issue

Allowed values

first_attemptfinal_attempt

connections

stringstring[]

Required

A pattern to match on the connection name or array of connection IDs. Use * as wildcard.

Transformation issue type configs

log_level

TransformationExecutionLogLevel

Required

The minimum log level to open the issue on

Allowed values

debuginfowarnerrorfatal

transformations

stringstring[]

Required

A pattern to match on the transformation name or array of transformation IDs. Use * as wildcard.

Backpressure issue type configs

delay

integer

Required

Min: 60000

Max: 86400000

The minimum delay (backpressure) to open the issue for min of 1 minute (60000) and max of 1 day (86400000)

destinations

stringstring[]

Required

A pattern to match on the destination name or array of destination IDs. Use * as wildcard.

Wildcard patterns

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

Retrieve all issue triggers

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

Query Parameters

name

string

Max length: 255

Filter by issue trigger name

type

IssueTypeIssueType[]

disabled_at

stringOperators

Date when the issue trigger was disabled

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-01/issue-triggers

Response example JSON

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "it_oK5SRphjGq3h7A"
  },
  "count": 1,
  "models": [
    {
      "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"
    }
  ]
}

Retrieve an issue trigger

This endpoint retrieves a specific issue trigger.

URL Parameters

string

Required

Issue trigger ID

GET

/2024-09-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

type

IssueType

Required

Issue type

Allowed values

deliverytransformationbackpressure

configs

IssueTriggerDeliveryConfigsIssueTriggerTransformationConfigsIssueTriggerBackpressureConfigs

Configuration object for the specific issue type selected

channels

IssueTriggerChannels

Required

Notification channels object for the specific channel type

name

string

Max length: 255

Optional unique name to use as reference when using the API

POST

/2024-09-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 Parameters

string

Required

Issue trigger ID

Body Parameters

configs

IssueTriggerDeliveryConfigsIssueTriggerTransformationConfigsIssueTriggerBackpressureConfigs

Configuration object for the specific issue type selected

channels

IssueTriggerChannels

Notification channels object for the specific channel type

disabled_at

string

Date

Date when the issue trigger was disabled

name

string

Max length: 255

Optional unique name to use as reference when using the API

PUT

/2024-09-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

type

IssueType

Required

Issue type

Allowed values

deliverytransformationbackpressure

configs

IssueTriggerDeliveryConfigsIssueTriggerTransformationConfigsIssueTriggerBackpressureConfigs

Configuration object for the specific issue type selected

channels

IssueTriggerChannels

Required

Notification channels object for the specific channel type

name

string

Required

Max length: 255

Required unique name to use as reference when using the API

PUT

/2024-09-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 Parameters

string

Required

Issue trigger ID

Disable an issue trigger

This endpoint disables an issue trigger.

URL Parameters

string

Required

Issue trigger ID

PUT

/2024-09-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 Parameters

string

Required

Issue trigger ID

PUT

/2024-09-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"
}

Transformations

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

Transformation Object

string

Required

ID of the transformation

team_id

string

Required

ID of the project

name

string

Required

A unique, human-friendly name for the transformation

code

string

Required

JavaScript code to be executed

env

object

Key-value environment variables to be passed to the transformation

updated_at

string

Required

Date

Date the transformation was last updated

created_at

string

Required

Date

Date the transformation was created

Example transformation object 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

Query Parameters

stringstring[]

Filter by transformation IDs

name

stringOperators

Filter by transformation name

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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 Parameters

string

Required

Transformation ID

GET

/2024-09-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

name

string

Required

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique, human-friendly name for the transformation

code

string

Required

JavaScript code to be executed as string

env

object

Key-value environment variables to be passed to the transformation

POST

/2024-09-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

name

string

Required

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique, human-friendly name for the transformation

code

string

Required

JavaScript code to be executed as string

env

object

Key-value environment variables to be passed to the transformation

PUT

/2024-09-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 Parameters

string

Required

Transformation ID

Body Parameters

name

string

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique, human-friendly name for the transformation

code

string

JavaScript code to be executed

env

object

Key-value environment variables to be passed to the transformation

PUT

/2024-09-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

env

object

Key-value environment variables to be passed to the transformation

webhook_id

string

ID of the connection to use for the execution context

code

string

JavaScript code to be executed

transformation_id

string

Transformation ID

request

object

Request input to use for the transformation execution

PUT

/2024-09-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.

URL Parameters

string

Required

Transformation ID

Query Parameters

log_level

stringstring[]

Log level of the execution

webhook_id

stringstring[]

ID of the connection the execution was run for

issue_id

stringstring[]

ID of the associated issue

created_at

stringOperators

ISO date of the transformation's execution

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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.

URL Parameters

string

Required

Transformation ID

execution_id

string

Required

Execution ID

GET

/2024-09-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"
}

Delete a Transformation

This endpoint permanently deletes a Transformation.

URL Parameters

string

Required

Transformation ID

Notifications

Notifications let your team receive alerts anytime an issue changes.

Webhook Notifications

This endpoint enables or disables webhook notifications for the project.

Body Parameters

enabled

boolean

Enable or disable webhook notifications on the project

topics

string[]

List of topics to send notifications for

source_id

string

The Hookdeck Source to send the webhook to

PUT

/2024-09-01/notifications/webhooks

Request body example JSON

{
  "request": {
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "enabled": true,
      "topics": [
        "issue.opened"
      ],
      "source_id": "src_9YmY0SHklrv6zBQz78cKGwSW"
    }
  }
}

Response example JSON

{
  "enabled": true,
  "topics": [
    "issue.opened"
  ],
  "source_id": "src_9YmY0SHklrv6zBQz78cKGwSW"
}

Requests

A request represent a HTTP request received by Hookdeck.

Request object

string

Required

ID of the request

team_id

string

Required

ID of the project

verified

boolean

Required

Whether or not the request was verified when received

original_event_data_id

string

Required

ID of the request data

rejection_cause

string

Required

Allowed values

SOURCE_DISABLEDNO_CONNECTIONVERIFICATION_FAILEDUNSUPPORTED_HTTP_METHODUNSUPPORTED_CONTENT_TYPE

ingest_priority

string

Required

The priority attributed to the request when received

Allowed values

NORMALLOW

ingested_at

string

Required

Date

The time the request was originally received

source_id

string

Required

ID of the associated source

events_count

integer

Required

The count of events created from this request (CLI events not included)

cli_events_count

integer

Required

The count of CLI events created from this request

updated_at

string

Required

Date

Date the event was last updated

created_at

string

Required

Date

Date the event was created

data

ShortEventData

Request data

Example request object JSON

{
  "id": "req_M3ltWOSF8G6oMS9GS9XX",
  "team_id": "tm_AkLVUIfTy4nn",
  "verified": false,
  "rejection_cause": null,
  "original_event_data_id": "edt_3DzFKL5UU8TKsXJjgct7",
  "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 ?ingested_at[gte]=2021-10-12&ingested_at[lte]=2021-10-13 to retrieve requests for that specific 24-hour period.

Requests past your organization archival window are not returned

Query Parameters

stringstring[]

Filter by requests IDs

status

string

Filter by status

Allowed values

acceptedrejected

rejection_cause

stringstring[]

Filter by rejection cause

source_id

stringstring[]

Filter by source IDs

verified

boolean

Filter by verification status

search_term

string

Min length: 3

URL Encoded string of the value to match partially to the body, headers, parsed_query or path

headers

JSON

URL Encoded string of the JSON to match to the data headers

body

JSON

URL Encoded string of the JSON to match to the data body

parsed_query

JSON

URL Encoded string of the JSON to match to the parsed query (JSON representation of the query)

path

string

URL Encoded string of the value to match partially to the path

ignored_count

integerOperatorsinteger[]

Filter by count of ignored events

events_count

integerOperatorsinteger[]

Filter by count of events

ingested_at

stringOperators

Filter by event ingested date

order_by

string

Max length: 255

Sort key

Allowed values

ingested_atcreated_at

dir

string

Sort direction

Allowed values

ascdesc

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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",
      "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 Parameters

string

Required

Request ID

GET

/2024-09-01/requests/:id

Response example JSON

{
  "id": "req_M3ltWOSF8G6oMS9GS9XX",
  "team_id": "tm_AkLVUIfTy4nn",
  "verified": false,
  "rejection_cause": null,
  "original_event_data_id": "edt_3DzFKL5UU8TKsXJjgct7",
  "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 Parameters

string

Required

Request ID

Body Parameters

webhook_ids

string[]

Required

Subset of webhook_ids to re-run the event logic on. Useful to retry only specific ignored_events

POST

/2024-09-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",
    "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 Parameters

string

Required

Request ID

Query Parameters

stringstring[]

Filter by event IDs

status

EventStatusEventStatus[]

Lifecyle status of the event

webhook_id

stringstring[]

Filter by webhook connection IDs

destination_id

stringstring[]

Filter by destination IDs

source_id

stringstring[]

Filter by source IDs

attempts

integerOperators

Filter by number of attempts

response_status

integerOperatorsinteger[]

Filter by HTTP response status code

successful_at

stringOperators

Filter by successful_at date using a date operator

created_at

stringOperators

Filter by created_at date using a date operator

error_code

AttemptErrorCodesAttemptErrorCodes[]

Filter by error code code

cli_id

stringobjectstring[]

Filter by CLI IDs. ?[any]=true operator for any CLI.

last_attempt_at

stringOperators

Filter by last_attempt_at date using a date operator

search_term

string

Min length: 3

URL Encoded string of the value to match partially to the body, headers, parsed_query or path

headers

JSON

URL Encoded string of the JSON to match to the data headers

body

JSON

URL Encoded string of the JSON to match to the data body

parsed_query

JSON

URL Encoded string of the JSON to match to the parsed query (JSON representation of the query)

path

string

URL Encoded string of the value to match partially to the path

order_by

string

Max length: 255

Sort key

Allowed values

last_attempt_atcreated_at

dir

string

Sort direction

Allowed values

ascdesc

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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 Parameters

string

Required

Request ID

Query Parameters

stringstring[]

Filter by ignored events IDs

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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": "DISABLED",
      "webhook_id": "web_I01KDNgvbS5G",
      "meta": null
    }
  ]
}

Events

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

Event object

string

Required

ID of the event

team_id

string

Required

ID of the project

webhook_id

string

Required

ID of the associated connection

source_id

string

Required

ID of the associated source

destination_id

string

Required

ID of the associated destination

event_data_id

string

Required

ID of the event data

request_id

string

Required

ID of the request that created the event

attempts

integer

Required

Number of delivery attempts made

last_attempt_at

string

Required

Date

Date of the most recently attempted retry

next_attempt_at

string

Required

Date

Date of the next scheduled retry

response_status

integer

Event status

error_code

AttemptErrorCodes

Error code of the delivery attempt

Allowed values

CANCELLEDTIMEOUTNOT_FOUNDCONNECTION_REFUSEDCONNECTION_RESET

status

EventStatus

Required

Allowed values

SCHEDULEDQUEUEDHOLDSUCCESSFULFAILED

successful_at

string

Required

Date

Date of the latest successful attempt

cli_id

string

Required

ID of the CLI the event is sent to

updated_at

string

Required

Date

Date the event was last updated

created_at

string

Required

Date

Date the event was created

data

ShortEventData

Request data

Example event object 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 CLI events

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

Query Parameters

stringstring[]

Filter by event IDs

status

EventStatusEventStatus[]

Lifecyle status of the event

webhook_id

stringstring[]

Filter by webhook connection IDs

destination_id

stringstring[]

Filter by destination IDs

source_id

stringstring[]

Filter by source IDs

attempts

integerOperators

Filter by number of attempts

response_status

integerOperatorsinteger[]

Filter by HTTP response status code

successful_at

stringOperators

Filter by successful_at date using a date operator

created_at

stringOperators

Filter by created_at date using a date operator

error_code

AttemptErrorCodesAttemptErrorCodes[]

Filter by error code code

cli_id

stringobjectstring[]

Filter by CLI IDs. ?[any]=true operator for any CLI.

last_attempt_at

stringOperators

Filter by last_attempt_at date using a date operator

search_term

string

Min length: 3

URL Encoded string of the value to match partially to the body, headers, parsed_query or path

headers

JSON

URL Encoded string of the JSON to match to the data headers

body

JSON

URL Encoded string of the JSON to match to the data body

parsed_query

JSON

URL Encoded string of the JSON to match to the parsed query (JSON representation of the query)

path

string

URL Encoded string of the value to match partially to the path

order_by

string

Max length: 255

Sort key

Allowed values

last_attempt_atcreated_at

dir

string

Sort direction

Allowed values

ascdesc

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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 request.

URL Parameters

string

Required

Event ID

GET

/2024-09-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 Parameters

string

Required

Event ID

POST

/2024-09-01/events/:id/retry

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-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": "/"
  }
}

Mute an event

This endpoint cancels the next automatic retry.

URL Parameters

string

Required

Event ID

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

PUT

/2024-09-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.

Attempt object

string

Required

Attempt ID

team_id

string

Required

ID of the project

event_id

string

Required

Event ID

destination_id

string

Required

Destination ID

response_status

integer

Attempt's HTTP response code

attempt_number

integer

Sequential number of attempts (up to and including this one) made for the associated event

trigger

AttemptTrigger

How the attempt was triggered

Allowed values

INITIALMANUALBULK_RETRYUNPAUSEAUTOMATIC

error_code

AttemptErrorCodes

Error code of the delivery attempt

Allowed values

CANCELLEDTIMEOUTNOT_FOUNDCONNECTION_REFUSEDCONNECTION_RESET

body

objectstring

requested_url

string

URL of the destination where delivery was attempted

http_method

string

HTTP method used to deliver the attempt

Allowed values

GETPOSTPUTPATCHDELETE

bulk_retry_id

string

ID of associated bulk retry

status

AttemptStatus

Required

Attempt status

Allowed values

FAILEDSUCCESSFUL

successful_at

string

Date

Date the attempt was successful

delivered_at

string

Date

Date the attempt was delivered

responded_at

string

Date

Date the destination responded to this attempt

delivery_latency

integer

Time elapsed between attempt initiation and final delivery (in ms)

response_latency

integer

Time elapsed between attempt initiation and a response from the destination (in ms)

updated_at

string

Required

Date

Date the attempt was last updated

created_at

string

Required

Date

Date the attempt was created

Example attempt object 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",
  "http_method": "POST"
}

Retrieve all attempts

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

Query Parameters

event_id

stringstring[]

Event the attempt is associated with

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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,
      "disabled_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. If the body is not yet available in our backend service the body will be set to NOT_AVAILABLE_YET.

URL Parameters

string

Required

Attempt ID

GET

/2024-09-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,
  "disabled_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/",
  "http_method": "POST"
}

Bookmarks

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

Bookmark object

string

Required

ID of the bookmark

team_id

string

Required

ID of the project

webhook_id

string

Required

ID of the associated connection

event_data_id

string

Required

ID of the bookmarked event data

label

string

Required

Descriptive name of the bookmark

alias

string

Alternate alias for the bookmark

data

ShortEventData

Request data

last_used_at

string

Date

Date the bookmark was last manually triggered

updated_at

string

Required

Date

Date the bookmark was last updated

created_at

string

Required

Date

Date the bookmark was created

Example bookmark object 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 Parameters

stringstring[]

Filter by bookmark IDs

name

stringstring[]

Filter by bookmark name

webhook_id

stringstring[]

Filter by associated connection ID

event_data_id

stringstring[]

Filter by associated event data ID

label

stringstring[]

Filter by label

last_used_at

stringOperators

Filter by last used date

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

Retrieve a bookmark

This endpoint retrieves a specific bookmark.

URL Parameters

string

Required

Bookmark ID

GET

/2024-09-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

event_data_id

string

Required

Max length: 255

ID of the event data to bookmark

webhook_id

string

Required

Max length: 255

ID of the associated connection

label

string

Required

Max length: 255

Descriptive name of the bookmark

name

string

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique, human-friendly name for the bookmark

POST

/2024-09-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 Parameters

string

Required

Bookmark ID

Body Parameters

event_data_id

string

Max length: 255

ID of the event data to bookmark

webhook_id

string

Max length: 255

ID of the associated connection

label

string

Max length: 255

Descriptive name of the bookmark

name

string

Pattern: ^[A-z0-9-_]+$

Max length: 155

A unique, human-friendly name for the bookmark

PUT

/2024-09-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 Parameters

string

Required

Bookmark ID

Body Parameters

target

string

Bookmark target

Allowed values

httpcli

The parameter last_used_at is set to the current timestamp.

POST

/2024-09-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 Parameters

string

Required

Bookmark ID

Issues

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

Issue object

string

Required

Issue ID

team_id

string

Required

ID of the project

status

IssueStatus

Required

Issue status

Allowed values

OPENEDIGNOREDACKNOWLEDGEDRESOLVED

opened_at

string

Required

Date

ISO timestamp for when the issue was last opened

first_seen_at

string

Required

Date

ISO timestamp for when the issue was first opened

last_seen_at

string

Required

Date

ISO timestamp for when the issue last occured

last_updated_by

string

Deprecated, will always be set to null

dismissed_at

string

Date

ISO timestamp for when the issue was dismissed

updated_at

string

Required

ISO timestamp for when the issue was last updated

created_at

string

Required

ISO timestamp for when the issue was created

type

string

Required

Allowed value

delivery

aggregation_keys

DeliveryIssueAggregationKeys

Required

Keys used as the aggregation keys a 'delivery' type issue

reference

DeliveryIssueReference

Required

Reference to the event and attempt an issue is being created for.

Example issue object 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/",
      "http_method": "POST"
    }
  }
}

Retrieve all issues

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

Dismissed issues are filtered out by default.

Query Parameters

stringstring[]

Filter by Issue IDs

issue_trigger_id

stringstring[]

Filter by Issue trigger IDs

type

stringstring[]

Filter by Issue types

status

stringstring[]

Filter by Issue statuses

merged_with

stringstring[]

Filter by Merged Issue IDs

aggregation_keys

JSON

Filter by aggregation keys

created_at

stringOperators

Filter by created dates

first_seen_at

stringOperators

Filter by first seen dates

last_seen_at

stringOperators

Filter by last seen dates

dismissed_at

stringOperators

Filter by dismissed dates

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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 Parameters

stringstring[]

Filter by Issue IDs

issue_trigger_id

stringstring[]

Filter by Issue trigger IDs

type

stringstring[]

Filter by Issue types

status

stringstring[]

Filter by Issue statuses

merged_with

stringstring[]

Filter by Merged Issue IDs

aggregation_keys

JSON

Filter by aggregation keys

created_at

stringOperators

Filter by created dates

first_seen_at

stringOperators

Filter by first seen dates

last_seen_at

stringOperators

Filter by last seen dates

dismissed_at

stringOperators

Filter by dismissed dates

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

Retrieve an issue

This endpoint retrieves a specific issue.

URL Parameters

string

Required

Issue ID

GET

/2024-09-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,
      "disabled_at": null,
      "body": {
        "example": true
      },
      "requested_url": "https://mock.hookdeck.com/",
      "http_method": "POST"
    }
  }
}

Update an issue

This endpoint updates an issue's status.

URL Parameters

string

Required

Issue ID

Body Parameters

status

string

Required

New status

Allowed values

OPENEDIGNOREDACKNOWLEDGEDRESOLVED

PUT

/2024-09-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,
      "disabled_at": null,
      "body": {
        "example": true
      },
      "requested_url": "https://mock.hookdeck.com/",
      "http_method": "POST"
    }
  }
}

Dismiss an issue

This endpoint marks an issue as dismissed.

URL Parameters

string

Required

Issue ID

The parameter dimissed_at is set to the current timestamp.

DELETE

/2024-09-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,
      "disabled_at": null,
      "body": {
        "example": true
      },
      "requested_url": "https://mock.hookdeck.com/",
      "http_method": "POST"
    }
  }
}

Bulk retry events

Event bulk retry object

string

Required

ID of the bulk retry

team_id

string

Required

ID of the project

query

JSON

Query object to filter records

created_at

string

Required

Date

Date the bulk retry was created

updated_at

string

Required

Date

Last time the bulk retry was updated

cancelled_at

string

Date

Date the bulk retry was cancelled

completed_at

string

Date

Date the bulk retry was completed

estimated_batch

integer

Number of batches required to complete the bulk retry

estimated_count

integer

Number of estimated events to be retried

processed_batch

integer

Number of batches currently processed

completed_count

integer

Number of events that were successfully delivered

in_progress

boolean

Required

Indicates if the bulk retry is currently in progress

progress

number

float

Progression of the batch operations, values 0 - 1

failed_count

integer

Number of events that failed to be delivered

Event 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
}

Retrieve all events bulk retries

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

Query Parameters

cancelled_at

stringOperators

Filter by date the bulk retry was cancelled

completed_at

stringOperators

Filter by date the bulk retry completed

created_at

stringOperators

Filter by date the bulk retry was created

stringstring[]

Filter by bulk retry IDs

query

JSON

Filter for events to be included in the bulk retry, use query parameters of Event

query_partial_match

boolean

Allow partial filter match on query property

in_progress

boolean

Indicates if the bulk retry is currently in progress

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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 Parameters

string

Required

Bulk retry ID

GET

/2024-09-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 Parameters

query

JSON

Filter properties for the events to be included in the bulk retry

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

query

JSON

Filter properties for the events to be included in the bulk retry

POST

/2024-09-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 Parameters

string

Required

Bulk retry ID

POST

/2024-09-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

Bulk retry object

string

Required

ID of the bulk retry

team_id

string

Required

ID of the project

query

JSON

Query object to filter records

created_at

string

Required

Date

Date the bulk retry was created

updated_at

string

Required

Date

Last time the bulk retry was updated

cancelled_at

string

Date

Date the bulk retry was cancelled

completed_at

string

Date

Date the bulk retry was completed

estimated_batch

integer

Number of batches required to complete the bulk retry

estimated_count

integer

Number of estimated events to be retried

processed_batch

integer

Number of batches currently processed

completed_count

integer

Number of events that were successfully delivered

in_progress

boolean

Required

Indicates if the bulk retry is currently in progress

progress

number

float

Progression of the batch operations, values 0 - 1

failed_count

integer

Number of events that failed to be delivered

Ignore events 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
}

Retrieve all ignored events bulk retries

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

Query Parameters

cancelled_at

stringOperators

Filter by date the bulk retry was cancelled

completed_at

stringOperators

Filter by date the bulk retry completed

created_at

stringOperators

Filter by date the bulk retry was created

stringstring[]

Filter by bulk retry IDs

query

JSON

Filter by the bulk retry ignored event query object

query_partial_match

boolean

Allow partial filter match on query property

in_progress

boolean

Indicates if the bulk retry is currently in progress

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-01/bulk/ignored-events/retry

Response example JSON

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 1,
    "next": "bch_YAONJuft9aQ0n3"
  },
  "count": 1,
  "models": [
    {
      "id": "bch_YAONJuft9aQ0n3",
      "team_id": "tm_Vn0Fn3sEqjGX",
      "query": {
        "cause": "TRANSFORMATION_FAILED",
        "transformation_id": "trs_XRyNGe8sta9SN9"
      },
      "updated_at": "2022-09-30T15:00:34.830Z",
      "created_at": "2022-09-30T15:00:33.550Z",
      "completed_at": null,
      "cancelled_at": null,
      "estimated_batch": 8,
      "estimated_count": 192,
      "processed_batch": 1,
      "completed_count": 25,
      "failed_count": 0,
      "number": 3,
      "in_progress": true,
      "progress": 0.13
    }
  ]
}

Retrieve a ignored events bulk retry

This endpoint retrieves a specific bulk retry.

URL Parameters

string

Required

Bulk retry ID

GET

/2024-09-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 Parameters

query

JSON

Filter by the bulk retry ignored event query object

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

query

JSON

Filter by the bulk retry ignored event query object

POST

/2024-09-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 Parameters

string

Required

Bulk retry ID

POST

/2024-09-01/bulk/ignored-events/retry/:id/cancel

Response example JSON

{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "cause": [
      "TRANSFORMATION_FAILED"
    ]
  },
  "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 requests

Bulk retry object

string

Required

ID of the bulk retry

team_id

string

Required

ID of the project

query

JSON

Query object to filter records

created_at

string

Required

Date

Date the bulk retry was created

updated_at

string

Required

Date

Last time the bulk retry was updated

cancelled_at

string

Date

Date the bulk retry was cancelled

completed_at

string

Date

Date the bulk retry was completed

estimated_batch

integer

Number of batches required to complete the bulk retry

estimated_count

integer

Number of estimated events to be retried

processed_batch

integer

Number of batches currently processed

completed_count

integer

Number of events that were successfully delivered

in_progress

boolean

Required

Indicates if the bulk retry is currently in progress

progress

number

float

Progression of the batch operations, values 0 - 1

failed_count

integer

Number of events that failed to be delivered

Requests 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
}

Retrieve all requests bulk retries

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

Query Parameters

cancelled_at

stringOperators

Filter by date the bulk retry was cancelled

completed_at

stringOperators

Filter by date the bulk retry completed

created_at

stringOperators

Filter by date the bulk retry was created

stringstring[]

Filter by bulk retry IDs

in_progress

boolean

Indicates if the bulk retry is currently in progress

query

JSON

Filter properties for the events to be included in the bulk retry, use query parameters of Requests

query_partial_match

boolean

Allow partial filter match on query property

order_by

stringstring[]

Sort key(s)

dir

stringstring[]

Sort direction(s)

limit

integer

Max: 255

Result set size

string

Max length: 255

The ID to provide in the query to get the next set of results

string

Max length: 255

The ID to provide in the query to get the previous set of results

GET

/2024-09-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_DISABLED"
        ]
      },
      "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 Parameters

string

Required

Bulk retry ID

GET

/2024-09-01/bulk/requests/retry/:id

Response example JSON

{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "rejection_cause": [
      "SOURCE_DISABLED"
    ]
  },
  "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 Parameters

query

JSON

Filter properties for the events to be included in the bulk retry, use query parameters of Requests

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

query

JSON

Filter properties for the events to be included in the bulk retry, use query parameters of Requests

POST

/2024-09-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_DISABLED"
    ]
  },
  "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 Parameters

string

Required

Bulk retry ID

POST

/2024-09-01/bulk/requests/retry/:id/cancel

Response example JSON

{
  "id": "blkr_6dxoWIomd8DQdH",
  "team_id": "tm_UkFg3CHYN50M",
  "query": {
    "rejection_cause": [
      "SOURCE_DISABLED"
    ]
  },
  "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 Connections using the rules field.

Retry

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

type

string

Required

A retry rule must be of type retry

Allowed value

retry

strategy

RetryStrategy

Required

Algorithm to use when calculating delay between retries

Allowed values

linearexponential

interval

integer

Time in MS between each retry

count

integer

Maximum number of retries to attempt

response_status_codes

string[]

HTTP codes to retry on. Accepts: range expressions (e.g., "400-499", ">400"), specific codes (e.g., 404), and exclusions (e.g., "!401"). Example: ["500-599", ">400", 404, "!401"]

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.

type

string

Required

A delay rule must be of type delay

Allowed value

delay

delay

integer

Required

Delay to introduce in MS

Filter

The filter rule allows you to permit and route events 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.

type

string

Required

A filter rule must be of type filter

Allowed value

filter

headers

JSON

JSON using our filter syntax to filter on request headers

body

JSON

JSON using our filter syntax to filter on request headers

query

JSON

JSON using our filter syntax to filter on request headers

path

JSON

JSON using our filter syntax to filter on request headers

Transform

The transform rule allows you to run arbitrary JavaScript to transform the event data.

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

type

string

Required

A transformation rule must be of type transformation

Allowed value

transform

transformation_id

string

ID of the attached transformation object. Optional input, always set once the rule is defined

transformation

object

You can optionally define a new transformation while creating a transform rule

Example re-using a transformation JSON

{
  "type": "transformation",
  "transformation_id": "trs_XRyNGe8sta9SN9"
}

Example with a new transformation JSON

{
  "type": "transformation",
  "transformation": {
    "name": "example",
    "code": "addHandler('transform', (request, context) => request)",
    "env": {
      "SECRET": "supersecret"
    }
  }
}