Getting Started
The Hookdeck REST API allows you to set up connections, retrieve events, and perform actions programmatically.
Hookdeck API was historically available on api.hookdeck.io and has been moved to api.hookdeck.com. The former will remain functional, but consider migrating to api.hookdeck.com.
Get an API key
You'll need to include an API key in every API request. If you do not yet have a Hookdeck account, please sign up for a free account. Your API key is located in your workspace settings.
To include your API key in requests, use either Bearer Token Authentication or Basic Authentication.
| 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 |
Terminal
curl "https://api.hookdeck.com/2022-10-01/events"
-H "Content-Type: application/json"
-H "Authorization: Bearer $API_KEY"
Create your first connection
Creating your first connection will allow you to start routing webhooks with Hookdeck.
The API only supports
application/jsonfor 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
urlorcli_pathis required.
Response
The response body returns objects for the associated source, destination, and ruleset.
These resources can be reused in future requests by passing the destination_id, source_id, or ruleset_id instead of an object.
Endpoint
HTTP
POST /2022-10-01/connectionsRequest body example
JSON
{
"name": "shopify-my-api",
"source": {
"name": "shopify"
},
"destination": {
"name": "my-api",
"url": "https://example.com/webhook"
}
}Response example
JSON
{
"id": "web_3tVBgTFuuzmEnsWa9eBywz6j",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.575Z",
"created_at": "2021-08-02T14:12:56.611Z",
"paused_at": null,
"name": "shopify-my-api",
"rules": [],
"destination": {
"id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://example.com/webhook",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.591Z",
"created_at": "2021-08-02T14:12:56.589Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": null,
"path_forwarding_disabled": false,
"name": "my-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.586Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": true,
"archived_at": null,
"updated_at": "2021-08-02T13:52:16.888Z",
"created_at": "2021-08-01T21:29:36.367Z",
"name": "default-ruleset",
"rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Example reusing resources
JSON
{
"name": "shopify-my-api",
"destination_id": "des_xxxxxxxxxxxxxxx",
"source_id": "src_xxxxxxxxxxxxxxx",
"ruleset_id": "rls_xxxxxxxxxxxxxxx"
}
Verify your first connection
Verifying the connection lets you know Hookdeck is properly ingesting and processing webhooks from your source.
Copy the unique Hookdeck URL and paste it into your API provider's webhook URL field. Test the connection by triggering a webhook on your source. As soon Hookdeck receives your first webhook, it'll appear in your dashboard.
The connection URL is a property of the webhook source object.
Congratulations! Your webhook events can now be viewed, inspected, filtered, sorted, retried, and more using Hookdeck.
JSON
{
"id": "web_xxxxxxxxxxxxxxx",
"source": {
"url": "https://events.hookdeck.com/e/src_xxxxxxxxxxxxxxx",
[...]
},
[...]
}
Authentication
Your API key is located in your workspace settings, and must be included in every API request. Use either Bearer Token Authentication or Basic Authentication.
| 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 |
Terminal
curl "https://api.hookdeck.com/2022-10-01/events"
-H "Content-Type: application/json"
-H "Authorization: Bearer $API_KEY"
Paging
All GET endpoints that retrieve a list of resources are paged using cursor (aka keyset) pagination, which resides in the response body's pagination object.
| 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.
If an event is pending, the keyset will return a truthy value (null) which will cause the pagination to omit null values in the response.
Pagination object
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 100,
"next": "web_2urj7h9puxk6obro3x",
"prev": "web_2urj7h9puxk6obuf6i"
}
}
Example to get the next page
Terminal
curl "https://api.hookdeck.com/2022-10-01/connections?next=web_2urj7h9puxk6obro3x"
-H "Authorization: Basic BASE64_API_TOKEN"
Example to get the previous page
Terminal
curl "https://api.hookdeck.com/2022-10-01/connections?previous=web_2urj7h9puxk6obuf6i"
-H "Authorization: Basic BASE64_API_TOKEN"
Example to get the next page without using the default ordering
Terminal
curl "https://api.hookdeck.com/2022-10-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.
Example response from an error
JSON
{
"handled": true,
"status": 422,
"message": "Webhook does not exist or is archived",
"data": {
"id": "web_xxxxxxxxxxx"
}
}
Rate Limits
The Hookdeck API has a rate limit of 240 request per minute, per API key. Contact us if you need your rate limit increased.
Rate limiting response headers
text
Retry-After: Seconds before next request can be made
X-RateLimit-Limit: Request per minute limit for the API key
X-RateLimit-Remaining: Remaining request for the rate limit period
X-RateLimit-Reset: ISO timestamp of the next rate limit period reset
Query Formatting
Arrays
Arrays in query parameters are indicated by a [] appended to their type, like string[].
For example: ?item[1]=hello&item[2]=world becomes ["hello", "world"]
Date
Dates are expected in ISO format.
For example: 2021-01-21T20:16:28Z or 2021-01-21
JSON
Some query parameters take JSON as input. The JSON should be stringified and URL encoded.
For example: ?body=%7B%0A%20%20"hello"%3A%20"world"%0A%7D becomes { "hello": "world" }
Operators
Most GET endpoints that retrieve a list of resources support operators as part of the request query.
For example: ?number[gte]=1&number[lte]=10
| 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 2022-10-01.
The API version can be set in the base path of any endpoint, such as $API_BASE_URL/sources. Otherwise the API defaults to the oldest supported stable version.
The backwards-incompatible changes for each version are listed below. Backwards-compatible changes don’t need a new API version and do not appear in this list.
2022-10-01
- Remove the properties
completed_event_idandlast_processed_event_idfrom the Event Bulk Retry model - Renamed the following properties on the Event Bulk Retry model
estimated_batch_counttoestimated_batchprocessed_batch_counttoprocessed_batchestimated_event_counttoestimated_countdelivered_event_counttocompleted_countfailed_event_counttofailed_count
- Added bulk retries for
requests
2022-07-01
- Renamed the
requestproperty todataon Events and Bookmarks - Renamed the
requestvalue todatawhen querying events with the data included, such that/events?include=requestis now/events?include=data - Renamed the
event_request_idproperty on Events and Bookmarks toevent_data_id
Introducing the Requests endpoint
- You can now use the Requests endpoint to retrieve the original requests that were received by Hookdeck, along with their associated events (including ignored events).
2022-03-01
- Removed the
intervalproperty from the Alert rule. Alert rule now controls how new issues are opened and notifications are now triggered by an issue opening or re-opening.
Introducing Issues
- You can now use the Issues endpoint to retrieve, update, and dismiss problems within your workspace.
Introducing Notifications by webhook
- You can now use the Notifications endpoint to configure webhook notifications for your workspace.
2021-08-01
- Removed the
labelproperty for Sources, Destinations, Rulesets and Connections. - Renamed the
aliasproperty tonamefor Sources, Destinations, Rulesets and Connections. - Removed the
alert_strategyandalert_intervalproperty for Rulesets. - Removed the
retry_strategy,retry_intervalandretry_countproperty for Rulesets. - Removed the
filtersproperty for Connections. - Added the
rulesproperty 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
2020-01-01 marks the intial released of the API.
Connections
A connection lets you route webhooks from a source to a destination, using a ruleset.
Connections were historically called "webhooks". The endpoint root path
/webhookshas been moved to/connections. The former will remain functional, but consider migrating to/connections.
Endpoints
HTTP
GET /2022-10-01/connections
GET /2022-10-01/connections/:id
POST /2022-10-01/connections
PUT /2022-10-01/connections
PUT /2022-10-01/connections/:id
PUT /2022-10-01/connections/:id/archive
PUT /2022-10-01/connections/:id/unarchive
PUT /2022-10-01/connections/:id/pause
PUT /2022-10-01/connections/:id/unpauseConnection object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the connection | |
| name | string | Unique name of the connection for this source | |
| team_id | string | ID of the workspace | |
| source | Source | Associated Source object | |
| destination | Destination | Associated Destination object | |
| ruleset | Ruleset | Workspace default ruleset | Associated Ruleset object |
| archived_at | date | null | Date the connection was archived |
| updated_at | date | Date the connection was last updated | |
| created_at | date | Date the connection was created | |
| resolved_rules | Rule[] | [] | Array of rules applied to connection after factoring for the ruleset |
| rules | Rule[] | [] | Array of rules configured on the connection |
JSON
{
"id": "web_mNP60lEYInVfnH1EUWbhfUYL",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T00:26:46.620Z",
"created_at": "2021-08-02T00:26:47.070Z",
"paused_at": null,
"name": "shopify-my-api",
"rules": [],
"destination": {
"id": "des_6MO6QjY7pOotcDaFZfw2hoWF",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://example.com/webhook",
"archived_at": null,
"updated_at": "2021-08-02T00:26:46.827Z",
"created_at": "2021-08-02T00:25:31.858Z",
"rate_limit": 5,
"rate_limit_period": "second",
"cli_path": null,
"path_forwarding_disabled": false,
"name": "my-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T00:26:46.816Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": true,
"archived_at": null,
"updated_at": "2021-08-02T00:26:46.649Z",
"created_at": "2021-08-01T21:29:36.367Z",
"name": "default-ruleset",
"rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}
Retrieve all connections
This endpoint lists all connections, or a subset of connections.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string[] | Filter by connection IDs |
| name | string | Filter by connection name |
| full_name | string | Fuzzy match the concatenated source and connection name |
| source_id | string[] | Associated Source ID |
| destination_id | string[] | Associated Destination id |
| archived | boolean | Include archived resources in the response |
| archived_at | date | Date the connection was archived |
| paused_at | date | Date the connection was paused |
| limit | number | Limit the returned event count (max 250) |
Endpoint
HTTP
GET /2022-10-01/connectionsResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "web_szbJuSoCxatxFytJdqdsfGHL"
},
"count": 1,
"models": [
{
"id": "web_szbJuSoCxatxFytJdqdsfGHL",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.407Z",
"created_at": "2021-08-02T14:09:56.133Z",
"paused_at": null,
"name": "example-destination",
"rules": [],
"destination": {
"id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:09:56.117Z",
"created_at": "2021-08-02T14:09:56.116Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "example-destination"
},
"ruleset": {
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.400Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"source": {
"id": "src_2Q0cNXCHyzPJCUOmpk76JKeU",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-01T21:48:16.865Z",
"created_at": "2021-08-01T21:45:07.100Z",
"name": "test",
"url": "https://events.hookdeck.com/e/src_2Q0cNXCHyzPJCUOmpk76JKeU"
},
"resolved_rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}
]
}Retrieve a connection
This endpoint retrieves a specific connection.
URL Parameter
| Parameter | Description |
|---|---|
| id | Webhook ID |
Endpoint
HTTP
GET /2022-10-01/connections/:idResponse example
JSON
{
"id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T13:52:40.344Z",
"created_at": "2021-08-01T21:29:41.818Z",
"paused_at": null,
"name": "mock-api",
"rules": [],
"destination": {
"id": "des_fYYCay655IHwbOMhIaUXtNq2",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:07:54.608Z",
"created_at": "2021-08-01T21:29:41.785Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "mock-api"
},
"ruleset": {
"id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": true,
"archived_at": null,
"updated_at": "2021-08-02T13:52:16.888Z",
"created_at": "2021-08-01T21:29:36.367Z",
"name": "default-ruleset",
"rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T13:52:17.030Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"resolved_rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Create a connection
This endpoint creates a connection.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | A unique name of the connection for the source |
| source_id | string | ID of a source to bind to the connection |
| destination_id | string | ID of a destination to bind to the connection |
| ruleset_id | string | ID of a rule to bind to the connection. Default to the Workspace default ruleset |
| source | Source | Source input object |
| destination | Destination | Destination input object |
| ruleset | Ruleset | Ruleset input object |
| rules | Rule[] | Array of rules to apply |
Create a connection with new resources
You can create a connection's underlying source, destination, and ruleset with a single call by declaring an object for any of those resources.
Create a connection with existing resources
You can reuse a source, destination, or ruleset by referencing their ID.
Endpoint
HTTP
POST /2022-10-01/connectionsRequest body example
JSON
{
"name": "shopify-my-api",
"source": {
"name": "shopify"
},
"destination": {
"name": "my-api",
"url": "https://example.com/webhook"
}
}Response example
JSON
{
"id": "web_3tVBgTFuuzmEnsWa9eBywz6j",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.575Z",
"created_at": "2021-08-02T14:12:56.611Z",
"paused_at": null,
"name": "shopify-my-api",
"rules": [],
"destination": {
"id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://example.com/webhook",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.591Z",
"created_at": "2021-08-02T14:12:56.589Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": null,
"path_forwarding_disabled": false,
"name": "my-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.586Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": true,
"archived_at": null,
"updated_at": "2021-08-02T13:52:16.888Z",
"created_at": "2021-08-01T21:29:36.367Z",
"name": "default-ruleset",
"rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Create connection with a new source and destination
JSON
{
"name": "github-some-api",
"source": {
"name": "github"
},
"destination": {
"name": "some-api",
"url": "https://example.com/webhook"
}
}
Create a connection reusing a source & destination
JSON
{
"source_id": "src_xxx",
"destination_id": "des_xxx"
}
Create/Update a connection
This endpoint creates a connection, or updates an existing connection by name.
A connection's source and destination cannot be updated.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Unique name of the connection for the source |
| source_id | string | ID of a source to bind to the connection |
| destination_id | string | ID of a destination to bind to the connection |
| ruleset_id | string | ID of a rule to bind to the connection. Default to the Workspace default ruleset |
| source | Source | Source input object |
| destination | Destination | Destination input object |
| ruleset | Ruleset | Ruleset input object |
| rules | Rule[] | Array of rules to apply |
Create/Update a connection with new resources
You can create a connection's underlying source, destination, and ruleset with a single call by declaring an object for any of those resources.
Create/Update a connection with existing resources
You can reuse a source, destination, or ruleset by referencing their ID.
Endpoint
HTTP
PUT /2022-10-01/connectionsRequest body example
JSON
{
"name": "shopify-my-api",
"source": {
"name": "shopify"
},
"destination": {
"name": "my-api",
"url": "https://example.com/webhook"
}
}Response example
JSON
{
"id": "web_3tVBgTFuuzmEnsWa9eBywz6j",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.696Z",
"created_at": "2021-08-02T14:12:56.611Z",
"paused_at": null,
"name": "shopify-my-api",
"rules": [],
"destination": {
"id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://example.com/webhook",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.671Z",
"created_at": "2021-08-02T14:12:56.589Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": null,
"path_forwarding_disabled": false,
"name": "my-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.674Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_gaqoPgyT17a8x1mBMpKnku8A",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": true,
"archived_at": null,
"updated_at": "2021-08-02T13:52:16.888Z",
"created_at": "2021-08-01T21:29:36.367Z",
"name": "default-ruleset",
"rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Update a connection
This endpoint updates a connection.
URL Parameter
| Parameter | Description |
|---|---|
| id | Webhook ID |
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Unique name of the connection for the source |
| ruleset_id | string | ID of a rule to bind to the connection. Default to the Workspace default ruleset |
| ruleset | Ruleset | Ruleset input object |
| rules | Rule[] | Array of rules to apply |
Endpoint
HTTP
PUT /2022-10-01/connections/:idRequest body example
JSON
{
"ruleset_id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ"
}Response example
JSON
{
"id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.748Z",
"created_at": "2021-08-01T21:29:41.818Z",
"paused_at": null,
"name": "mock-api",
"rules": [],
"destination": {
"id": "des_fYYCay655IHwbOMhIaUXtNq2",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:07:54.608Z",
"created_at": "2021-08-01T21:29:41.785Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "mock-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.674Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.400Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Pause a connection
This endpoint pauses a connection.
A paused connection will still receive events, but those events will be marked with a status of HOLD and will be delivered only once the connection is unpaused.
URL Parameter
| Parameter | Description |
|---|---|
| id | Connection ID |
The parameter
paused_atis set to the current timestamp.
Endpoint
HTTP
PUT /2022-10-01/connections/:id/pauseResponse example
JSON
{
"id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.779Z",
"created_at": "2021-08-01T21:29:41.818Z",
"paused_at": "2021-08-02T14:12:56.779Z",
"name": "mock-api",
"rules": [],
"destination": {
"id": "des_fYYCay655IHwbOMhIaUXtNq2",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:07:54.608Z",
"created_at": "2021-08-01T21:29:41.785Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "mock-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.674Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.400Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Unpause a connection
This endpoint unpauses a connection.
Any event with a status of HOLD will be attempted (rate limits will be respected). This operation is asynchronous, so it may take some time for all events to be QUEUED for delivery.
URL Parameter
| Parameter | Description |
|---|---|
| id | Connection ID |
The parameter
paused_atis set tonull.
Endpoint
HTTP
PUT /2022-10-01/connections/:id/unpauseResponse example
JSON
{
"id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.813Z",
"created_at": "2021-08-01T21:29:41.818Z",
"paused_at": null,
"name": "mock-api",
"rules": [],
"destination": {
"id": "des_fYYCay655IHwbOMhIaUXtNq2",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:07:54.608Z",
"created_at": "2021-08-01T21:29:41.785Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "mock-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.674Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.400Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Archive a connection
This endpoint archives a connection.
An archived connection will no longer receive or deliver any webhooks.
URL Parameter
| Parameter | Description |
|---|---|
| id | Connection ID |
The parameter
archived_atis set to the current timestamp.
Endpoint
HTTP
PUT /2022-10-01/connections/:id/archiveResponse example
JSON
{
"id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": "2021-08-02T14:12:56.779Z",
"updated_at": "2021-08-02T14:12:56.779Z",
"created_at": "2021-08-01T21:29:41.818Z",
"paused_at": null,
"name": "mock-api",
"rules": [],
"destination": {
"id": "des_fYYCay655IHwbOMhIaUXtNq2",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:07:54.608Z",
"created_at": "2021-08-01T21:29:41.785Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "mock-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.674Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.400Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Unarchive a connection
This endpoint unarchives a connection.
The associated source and destination will also be unarchived if they were previously archived.
URL Parameter
| Parameter | Description |
|---|---|
| id | Connection ID |
The parameter
archived_atis set tonull.
Endpoint
HTTP
PUT /2022-10-01/connections/:id/unarchiveResponse example
JSON
{
"id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.813Z",
"created_at": "2021-08-01T21:29:41.818Z",
"paused_at": null,
"name": "mock-api",
"rules": [],
"destination": {
"id": "des_fYYCay655IHwbOMhIaUXtNq2",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:07:54.608Z",
"created_at": "2021-08-01T21:29:41.785Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "mock-api"
},
"source": {
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.674Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
},
"ruleset": {
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.400Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
},
"resolved_rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Sources
A source represents any third party that sends webhooks to Hookdeck.
Endpoints
HTTP
GET /2022-10-01/sources
GET /2022-10-01/sources/:id
POST /2022-10-01/sources
PUT /2022-10-01/sources
PUT /2022-10-01/sources/:id
PUT /2022-10-01/sources/:id/archive
PUT /2022-10-01/sources/:id/unarchiveSource object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the source | |
| team_id | string | ID of the workspace | |
| name | string | Name for the source | |
| archived_at | date | null | Date the source was archived |
| updated_at | date | Date the source was last updated | |
| created_at | date | Date the source was created |
Using the source URL
The source object contains a unique URL that must be supplied to your webhook's provider. Each valid HTTP POST request received at this URL creates an event.
JSON
{
"id": "src_1b69dxk87s0g4k",
"team_id": "tm_5b3mzbxk83c0k7i",
"name": "shopify-prod",
"archived_at": null,
"updated_at": "2020-03-25T20:46:26.742Z",
"created_at": "2020-03-25T20:24:14.069Z",
"url": "https://events.hookdeck.com/e/src_1b69dxk87s0g4k"
}
Retrieve all sources
This endpoint lists all sources, or a subset of sources.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string[] | Filter by source IDs |
| name | string | The source name |
| archived | boolean | Include archived resources in the response |
| archived_at | date | Date the source was archived |
| limit | number | Limit the returned source count (max 250) |
Endpoint
HTTP
GET /2022-10-01/sourcesResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "src_2Q0cNXCHyzPJCUOmpk76JKeU"
},
"count": 1,
"models": [
{
"id": "src_2Q0cNXCHyzPJCUOmpk76JKeU",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-01T21:48:16.865Z",
"created_at": "2021-08-01T21:45:07.100Z",
"name": "test",
"url": "https://events.hookdeck.com/e/src_2Q0cNXCHyzPJCUOmpk76JKeU"
}
]
}Retrieve a source
This endpoint retrieves a specific source.
URL Parameter
| Parameter | Description |
|---|---|
| id | Source ID |
Endpoint
HTTP
GET /2022-10-01/sources/:idResponse example
JSON
{
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.674Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}Create a source
This endpoint creates a source.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | A unique name for the source |
Endpoint
HTTP
POST /2022-10-01/sourcesRequest body example
JSON
{
"name": "shopify"
}Response example
JSON
{
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:57.327Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}Create/Update a source
This endpoint creates a source, or updates an existing source by name.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | A unique name for the source |
Endpoint
HTTP
PUT /2022-10-01/sourcesRequest body example
JSON
{
"name": "shopify"
}Response example
JSON
{
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:57.327Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}Update a source
This endpoint updates a source.
URL Parameter
| Parameter | Description |
|---|---|
| id | Source ID |
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | A unique name for the source |
Endpoint
HTTP
PUT /2022-10-01/sources/:idRequest body example
JSON
{
"name": "shopify"
}Response example
JSON
{
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": null,
"updated_at": "2021-08-02T14:12:57.347Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}Archive a source
This endpoint archives a source and any associated connections.
URL Parameter
| Parameter | Description |
|---|---|
| id | Source ID |
The parameter
archived_atis set to the current timestamp.
Endpoint
HTTP
PUT /2022-10-01/sources/:id/archiveResponse example
JSON
{
"id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"archived_at": "2021-08-02T14:12:57.370Z",
"updated_at": "2021-08-02T14:12:57.383Z",
"created_at": "2021-08-01T21:29:41.788Z",
"name": "shopify",
"url": "https://events.hookdeck.com/e/src_9YmY0SHklrv6zBQz78cKGwSW"
}Unarchive a source
This endpoint unarchives a source.
URL Parameter
| Parameter | Description |
|---|---|
| id | Source ID |
The parameter
archived_atis set tonull.
Endpoint
HTTP
PUT /2022-10-01/sources/:id/unarchiveResponse example
JSON
Missing dataDestinations
A destination is any endpoint to which your webhooks can be routed.
Endpoints
HTTP
GET /2022-10-01/destinations
GET /2022-10-01/destinations/:id
POST /2022-10-01/destinations
PUT /2022-10-01/destinations
PUT /2022-10-01/destinations/:id
PUT /2022-10-01/destinations/:id/archive
PUT /2022-10-01/destinations/:id/unarchiveDestination object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the destination | |
| team_id | string | ID of the workspace | |
| name | string | A unique, human-friendly name for the destination | |
| url | url | HTTP endpoint of the destination | |
| cli_path | string | Path for the CLI destination | |
| rate_limit | number | Limit event attempts to receive per period. Max value is workspace plan's max attempts thoughput, as defined here | |
| rate_limit_period | string | 'second' | Period to rate limit attempts (second, minute or hour) |
| archived_at | date | null | Date the destination was archived |
| updated_at | date | Date the destination was last updated | |
| created_at | date | Date the destination was created |
JSON
{
"id": "des_5b3mzbxk83dciim",
"team_id": "tm_5b3mzbxk83c0k7i",
"name": "my-api",
"url": "https://example.com/webhook",
"cli_path": "/webhook",
"rate_limit": 5,
"rate_limit_period": "second",
"archived_at": null,
"updated_at": "2020-03-26T17:15:31.079Z",
"created_at": "2020-03-22T18:22:38.015Z"
}
Retrieve all destinations
This endpoint lists all destinations, or a subset of destinations.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string[] | Filter by destination IDs |
| name | string | The destination name |
| archived | boolean | Include archived resources in the response |
| archived_at | date | Date the destination was archived |
| url | string | HTTP endpoint of the destination |
| cli_path | string | Path for the CLI destination |
| limit | number | Limit the returned event count (max 250) |
Endpoint
HTTP
GET /2022-10-01/destinationsResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "des_Nm49lhZV6wVrN1XFFPfkv7Zk"
},
"count": 1,
"models": [
{
"id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://example.com/webhook",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.671Z",
"created_at": "2021-08-02T14:12:56.589Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": null,
"path_forwarding_disabled": false,
"name": "my-api"
}
]
}Retrieve a destination
This endpoint retrieves a specific destination.
URL Parameter
| Parameter | Description |
|---|---|
| id | Destination ID |
Endpoint
HTTP
GET /2022-10-01/destinations/:idResponse example
JSON
{
"id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:09:56.117Z",
"created_at": "2021-08-02T14:09:56.116Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "example-destination"
}Create a destination
This endpoint creates a destination.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Name for the destination |
| url | url | Endpoint of the destination |
| cli_path | string | Path for the CLI destination |
| rate_limit | number | Limit event attempts to receive per period. Max 100/second or 6000/minute |
| rate_limit_period | string | Period to rate limit attempts (second, minute or hour) |
One of
urlorcli_pathis required.
Endpoint
HTTP
POST /2022-10-01/destinationsRequest body example
JSON
{
"name": "my-api",
"url": "https://example.com/webhook",
"rate_limit": 5,
"rate_limit_period": "second"
}Response example
JSON
{
"id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://example.com/webhook",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.933Z",
"created_at": "2021-08-02T14:12:56.589Z",
"rate_limit": 5,
"rate_limit_period": "second",
"cli_path": null,
"path_forwarding_disabled": false,
"name": "my-api"
}Create/Update a destination
This endpoint creates a destination, or updates an existing destination by name.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Name for the destination |
| url | url | Endpoint of the destination |
| rate_limit | number | Limit event attempts to receive per period. Max 100/second or 6000/minute |
| rate_limit_period | string | Period to rate limit attempts (second, minute or hour) |
Endpoint
HTTP
PUT /2022-10-01/destinationsRequest body example
JSON
{
"name": "my-api",
"url": "https://example.com/webhook",
"rate_limit": 5,
"rate_limit_period": "second"
}Response example
JSON
{
"id": "des_Nm49lhZV6wVrN1XFFPfkv7Zk",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://example.com/webhook",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.933Z",
"created_at": "2021-08-02T14:12:56.589Z",
"rate_limit": 5,
"rate_limit_period": "second",
"cli_path": null,
"path_forwarding_disabled": false,
"name": "my-api"
}Update a destination
This endpoint updates a destination.
URL Parameter
| Parameter | Description |
|---|---|
| id | Destination ID |
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Name for the destination |
| url | url | Endpoint of the destination |
| cli_path | string | Path for the CLI destination |
| rate_limit | number | Limit event attempts to receive per period. Max 100/second or 6000/minute |
| rate_limit_period | string | Period to rate limit attempts (second, minute or hour) |
Endpoint
HTTP
PUT /2022-10-01/destinations/:idRequest body example
JSON
{
"name": "my-new-api"
}Response example
JSON
{
"id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:12:56.960Z",
"created_at": "2021-08-02T14:09:56.116Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "my-new-api"
}Archive a destination
This endpoint archives a destination.
URL Parameter
| Parameter | Description |
|---|---|
| id | Destination ID |
The parameter
archived_atis set to the current timestamp.
Endpoint
HTTP
PUT /2022-10-01/destinations/:id/archiveResponse example
JSON
{
"id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": "2021-08-02T14:12:57.042Z",
"updated_at": "2021-08-02T14:12:57.042Z",
"created_at": "2021-08-02T14:09:56.116Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "my-new-api"
}Unarchive a destination
This endpoint unarchives a destination.
URL Parameter
| Parameter | Description |
|---|---|
| id | Destination ID |
The parameter
archived_atis set tonull.
Endpoint
HTTP
PUT /2022-10-01/destinations/:id/unarchiveResponse example
JSON
{
"id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"url": "https://mock.hookdeck.com",
"archived_at": null,
"updated_at": "2021-08-02T14:12:57.042Z",
"created_at": "2021-08-02T14:09:56.116Z",
"rate_limit": null,
"rate_limit_period": "second",
"cli_path": "/",
"path_forwarding_disabled": false,
"name": "my-new-api"
}Rulesets
A ruleset defines a group of rules that can be used across many connections.
Endpoints
HTTP
GET /2022-10-01/rulesets
GET /2022-10-01/rulesets/:id
POST /2022-10-01/rulesets
PUT /2022-10-01/rulesets
PUT /2022-10-01/rulesets/:id
PUT /2022-10-01/rulesets/:id/archive
PUT /2022-10-01/rulesets/:id/unarchiveRuleset object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the ruleset | |
| team_id | string | ID of the workspace | |
| name | string | null | A unique name for the ruleset |
| rules | Rule[] | [] | Array of rules to apply |
| is_team_default | boolean | true | Default ruleset of Workspace |
| archived_at | date | null | Date the ruleset was archived |
| updated_at | date | Date the ruleset was last updated | |
| created_at | date | Date the ruleset was created |
JSON
{
"id": "rls_5b3mzbxk83c0k89",
"name": "default-ruleset",
"team_id": "tm_5b3mzbxk83c0k7i",
"rules": [
{
"type": "retry",
"count": 5,
"interval": 10800000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
],
"is_team_default": true,
"archived_at": null,
"updated_at": "2020-03-22T17:45:20.742Z",
"created_at": "2020-03-22T17:45:20.746Z"
}
Retrieve all rulesets
This endpoint lists all rulesets, or a subset of rulesets.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string[] | Filter by ruleset IDs |
| name | string | The ruleset name |
| archived | boolean | Include archived resources in the response |
| archived_at | date | Date the ruleset was archived |
| limit | number | Limit the returned event count (max 250) |
Endpoint
HTTP
GET /2022-10-01/rulesetsResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "rls_YZCDPNVHORE8BZ86aDRyRMtZ"
},
"count": 1,
"models": [
{
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.400Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}
]
}Retrieve a ruleset
This endpoint retrieves a specific ruleset.
URL Parameter
| Parameter | Description |
|---|---|
| id | Ruleset ID |
Endpoint
HTTP
GET /2022-10-01/rulesets/:idResponse example
JSON
{
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:10:47.400Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "alert",
"interval": 86400000,
"strategy": "last_attempt"
}
]
}Create a ruleset
This endpoint creates a ruleset.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Name for the ruleset |
| rules | Rule[] | Array of rules to apply |
Endpoint
HTTP
POST /2022-10-01/rulesetsRequest body example
JSON
{
"name": "fast-retry-ruleset",
"rules": [
{
"type": "retry",
"strategy": "linear",
"count": 10,
"interval": 60000
},
{
"type": "alert",
"interval": 3600000,
"strategy": "last_attempt"
}
]
}Response example
JSON
{
"id": "rls_YreVNPlduZdaCIF1cDf2a11u",
"name": "fast-retry-ruleset",
"rules": [
{
"type": "retry",
"count": 10,
"interval": 60000,
"strategy": "linear"
},
{
"type": "alert",
"interval": 3600000,
"strategy": "last_attempt"
}
],
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"created_at": "2021-08-02T14:12:57.131Z",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:12:57.132Z"
}Create/Update a ruleset
This endpoint creates a ruleset, or updates an existing ruleset by name.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Name for the ruleset |
| rules | Rule[] | Array of rules to apply |
Endpoint
HTTP
PUT /2022-10-01/rulesetsRequest body example
JSON
{
"name": "fast-retry-ruleset",
"rules": [
{
"type": "retry",
"strategy": "linear",
"count": 10,
"interval": 60000
}
]
}Response example
JSON
{
"id": "rls_YreVNPlduZdaCIF1cDf2a11u",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:12:57.156Z",
"created_at": "2021-08-02T14:12:57.131Z",
"name": "fast-retry-ruleset",
"rules": [
{
"type": "retry",
"count": 10,
"interval": 60000,
"strategy": "linear"
}
]
}Update a ruleset
This endpoint updates a ruleset.
URL Parameter
| Parameter | Description |
|---|---|
| id | Ruleset ID |
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Naame for the ruleset |
| rules | Rule[] | Array of rules to apply |
Endpoint
HTTP
PUT /2022-10-01/rulesets/:idRequest body example
JSON
{
"rules": [
{
"type": "retry",
"strategy": "linear",
"count": 10,
"interval": 60000
}
]
}Response example
JSON
{
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:12:57.183Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "retry",
"count": 10,
"interval": 60000,
"strategy": "linear"
}
]
}Archive a ruleset
This endpoint archives a ruleset.
URL Parameter
| Parameter | Description |
|---|---|
| id | Ruleset ID |
The parameter
archived_atis set to the current timestamp.
Endpoint
HTTP
PUT /2022-10-01/rulesets/:id/archiveResponse example
JSON
{
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": "2021-08-02T14:12:57.236Z",
"updated_at": "2021-08-02T14:12:57.236Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "retry",
"count": 10,
"interval": 60000,
"strategy": "linear"
}
]
}Unarchive a ruleset
This endpoint unarchives a ruleset.
URL Parameter
| Parameter | Description |
|---|---|
| id | Ruleset ID |
The parameter
archived_atis set tonull.
Endpoint
HTTP
PUT /2022-10-01/rulesets/:id/unarchiveResponse example
JSON
{
"id": "rls_YZCDPNVHORE8BZ86aDRyRMtZ",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"is_team_default": false,
"archived_at": null,
"updated_at": "2021-08-02T14:12:57.236Z",
"created_at": "2021-08-02T14:10:47.399Z",
"name": "example-ruleset",
"rules": [
{
"type": "retry",
"count": 10,
"interval": 60000,
"strategy": "linear"
}
]
}Requests
A request represent a webhook received by Hookdeck.
Endpoints
HTTP
GET /2022-10-01/requests
GET /2022-10-01/requests/:id
POST /2022-10-01/requests/:id/retry
GET /2022-10-01/requests/:id/events
GET /2022-10-01/requests/:id/ignored_eventsRequest object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the request | |
| team_id | string | ID of the workspace | |
| verified | boolean | false | Weither or not the request was verified when received |
| source_id | string | ID of the associated source | |
| rejection_cause | string | null | Cause for which the request was rejection and not processed. One of SOURCE_ARCHIVED, NO_WEBHOOK, VERIFICATION_FAILED, UNSUPPORTED_HTTP_METHOD, UNSUPPORTED_CONTENT_TYPE, UNPARSABLE_JSON, PAYLOAD_TOO_LARGE |
| original_event_data_id | string | ID of the request data | |
| duplicate_hash | string | null | Hash of the request data payload used to check for duplicates |
| duplicate_hits | number | 0 | Count of duplicate hits found |
| attempts | number | 0 | Number of delivery attempts made |
| ingest_priority | string | NORMAL | The priority attributed to the request when received. One of LOW or NORMAL |
| ingested_at | date | The time the request was originally received | |
| events_count | number | 0 | The count of events created from this request (CLI events not included) |
| cli_events_count | number | 0 | The count of CLI events created from this request |
| updated_at | date | Date the event was last updated | |
| created_at | date | Date the event was created |
JSON
{
"id": "req_M3ltWOSF8G6oMS9GS9XX",
"team_id": "tm_AkLVUIfTy4nn",
"verified": false,
"rejection_cause": null,
"original_event_data_id": "edt_3DzFKL5UU8TKsXJjgct7",
"duplicate_hash": null,
"duplicate_hits": null,
"ingest_priority": "NORMAL",
"events_count": 2,
"cli_events_count": 0,
"ignored_count": 4,
"ingested_at": "2022-07-29T13:55:10.238Z",
"source_id": "src_iEfHpkswbzGW",
"updated_at": "2022-07-29T13:55:15.369Z",
"created_at": "2022-07-29T13:55:15.092Z"
}
Retrieve all requests
This endpoint lists all request, or a subset of requests.
Requests are sorted by ingested_at date.
Filtering requests
To filter the list of requests, use only supported operators.
For example, append ?created_at[gte]=2021-10-12&created_at[lte]=2021-10-13 to retrieve requests for that specific 24-hour period.
Requests past your workspace archival window are not returned
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string[] | Filter by requests IDs |
| rejection_cause | string[] | Filter by rejection cause |
| source_id | string[] | Filter by source IDs |
| verified | boolean | Filter by verification status |
| body | JSON | URL Encoded string of the JSON to match to the data body |
| headers | JSON | URL Encoded string of the JSON to match to the data headers |
| parsed_query | JSON | URL Encoded string of the JSON to match to the parsed query (JSON representation of the query) |
| path | string | URL Encoded string of the string to match partially to the path |
| limit | string | Limit the returned request count (max 250) |
Endpoint
HTTP
GET /2022-10-01/requestsResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "req_sE7L2cs1Ftn5nUlb8feF"
},
"count": 1,
"models": [
{
"id": "req_sE7L2cs1Ftn5nUlb8feF",
"team_id": "tm_AkLVUIfTy4nn",
"verified": false,
"rejection_cause": null,
"original_event_data_id": "edt_sUZBRp413JM6OSNJk6qc",
"duplicate_hash": null,
"duplicate_hits": null,
"ingest_priority": "NORMAL",
"ingested_at": "2022-07-29T13:54:26.514Z",
"source_id": "src_iEfHpkswbzGW",
"updated_at": "2022-07-29T13:55:20.360Z",
"created_at": "2022-07-29T13:55:20.330Z",
"events_count": 2,
"cli_events_count": 0,
"ignored_count": 4
}
]
}Retrieve a request
This endpoint retrieves a specific request.
The response contains the data object with the properties body, headers, path and query representing the original data for that request.
URL Parameter
| Parameter | Description |
|---|---|
| id | Request ID |
Endpoint
HTTP
GET /2022-10-01/requests/:idResponse example
JSON
{
"id": "req_M3ltWOSF8G6oMS9GS9XX",
"team_id": "tm_AkLVUIfTy4nn",
"verified": false,
"rejection_cause": null,
"original_event_data_id": "edt_3DzFKL5UU8TKsXJjgct7",
"duplicate_hash": null,
"duplicate_hits": null,
"ingest_priority": "NORMAL",
"ingested_at": "2022-07-29T13:55:10.238Z",
"source_id": "src_iEfHpkswbzGW",
"updated_at": "2022-07-29T13:55:15.369Z",
"created_at": "2022-07-29T13:55:15.092Z",
"events_count": 2,
"cli_events_count": 0,
"ignored_count": 4,
"data": {
"headers": {
"content-length": "18",
"content-type": "application/json",
"postman-token": "56fcfa62-9d0e-450f-a638-474b88f928ea",
"user-agent": "PostmanRuntime/7.29.2",
"x-hookdeck-original-ip": "172.18.0.1"
},
"body": {
"example": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
}Retry a request
This endpoint triggers a retry for an eligible request. The response contains the updated request and an array of created events if any were created.
URL Parameter
| Parameter | Description |
|---|---|
| id | Request ID |
Body Parameter
| Parameter | Type | Description |
|---|---|---|
| webhook_ids | string[] | Subset of webhook_ids to re-run the event logic on. Useful to retry only specific ignored_events |
Endpoint
HTTP
POST /2022-10-01/requests/:id/retryResponse example
JSON
{
"request": {
"id": "req_M3ltWOSF8G6oMS9GS9XX",
"team_id": "tm_AkLVUIfTy4nn",
"verified": false,
"rejection_cause": null,
"original_event_data_id": "edt_3DzFKL5UU8TKsXJjgct7",
"duplicate_hash": null,
"duplicate_hits": null,
"ingest_priority": "NORMAL",
"ingested_at": "2022-07-29T13:55:10.238Z",
"source_id": "src_iEfHpkswbzGW",
"updated_at": "2022-07-29T13:55:15.369Z",
"created_at": "2022-07-29T13:55:15.092Z",
"events_count": 1,
"cli_events_count": 0,
"ignored_count": 0,
"data": {
"headers": {
"content-length": "18",
"content-type": "application/json",
"postman-token": "56fcfa62-9d0e-450f-a638-474b88f928ea",
"user-agent": "PostmanRuntime/7.29.2",
"x-hookdeck-original-ip": "172.18.0.1"
},
"body": {
"example": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
},
"events": [
{
"id": "evt_wP4CcyPTYjwndo3R2s",
"team_id": "tm_AkLVUIfTy4nn",
"webhook_id": "web_lfMH5m6GpkO1",
"source_id": "src_iEfHpkswbzGW",
"destination_id": "des_hBX0AHpP3lji",
"attempts": 1,
"response_status": 200,
"last_attempt_at": "2022-07-29T13:55:16.420Z",
"next_attempt_at": null,
"successful_at": "2022-07-29T13:55:16.607Z",
"updated_at": "2022-07-29T13:55:16.609Z",
"created_at": "2022-07-29T13:55:15.291Z",
"status": "SUCCESSFUL",
"cli_id": null,
"request_id": "req_M3ltWOSF8G6oMS9GS9XX",
"event_data_id": "edt_3DzFKL5UU8TKsXJjgct7"
}
]
}Retrieve request events
This endpoint retries the events associated with a request.
URL Parameter
| Parameter | Description |
|---|---|
| id | Request ID |
Params
The supported params are the same to retrieve a list of events found here
Endpoint
HTTP
GET /2022-10-01/requests/:id/eventsResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 100
},
"count": 1,
"models": [
{
"id": "evt_wP4CcyPTYjwndo3R2s",
"team_id": "tm_AkLVUIfTy4nn",
"webhook_id": "web_lfMH5m6GpkO1",
"source_id": "src_iEfHpkswbzGW",
"destination_id": "des_hBX0AHpP3lji",
"attempts": 1,
"response_status": 200,
"last_attempt_at": "2022-07-29T13:55:16.420Z",
"next_attempt_at": null,
"successful_at": "2022-07-29T13:55:16.607Z",
"updated_at": "2022-07-29T13:55:16.609Z",
"created_at": "2022-07-29T13:55:15.291Z",
"status": "SUCCESSFUL",
"cli_id": null,
"request_id": "req_M3ltWOSF8G6oMS9GS9XX",
"event_data_id": "edt_3DzFKL5UU8TKsXJjgct7"
}
]
}Retrieve request ignored events
This endpoint retries the events associated with a request.
URL Parameter
| Parameter | Description |
|---|---|
| id | Request ID |
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string[] | Filter by ignored events IDs |
| limit | string | Limit the returned event count (max 250) |
Endpoint
HTTP
GET /2022-10-01/requests/:id/ignored_eventsResponse example
JSON
{
"pagination": {
"order_by": "id",
"dir": "desc",
"limit": 100
},
"count": 3,
"models": [
{
"request_id": "req_M3ltWOSF8G6oMS9GS9XX",
"team_id": "tm_AkLVUIfTy4nn",
"ignored_event_cause_id": 1475491804,
"id": 1475491804,
"cause": "FILTERED",
"webhook_id": "web_E2iWnvsY0RQE",
"meta": [
"body"
]
},
{
"request_id": "req_M3ltWOSF8G6oMS9GS9XX",
"team_id": "tm_AkLVUIfTy4nn",
"ignored_event_cause_id": 570221994,
"id": 570221994,
"cause": "CLI_DISCONNECTED",
"webhook_id": "web_Tqy2KliIrX1A",
"meta": null
},
{
"request_id": "req_M3ltWOSF8G6oMS9GS9XX",
"team_id": "tm_AkLVUIfTy4nn",
"ignored_event_cause_id": -1330322110,
"id": -1330322110,
"cause": "ARCHIVED",
"webhook_id": "web_I01KDNgvbS5G",
"meta": null
}
]
}Events
An event is any request that Hookdeck receives from a source.
Endpoints
HTTP
GET /2022-10-01/events
GET /2022-10-01/events/:id
POST /2022-10-01/events/:id/retry
PUT /2022-10-01/events/:id/muteEvent object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the event | |
| team_id | string | ID of the workspace | |
| webhook_id | string | ID of the associated connection | |
| source_id | string | ID of the associated source | |
| destination_id | string | ID of the associated destination | |
| cli_id | string | null | ID of the CLI the event is sent to |
| request_id | string | ID of the request that created the event | |
| event_data_id | string | ID of the request data | |
| attempts | number | 0 | Number of delivery attempts made |
| status | string | null | Lifecyle status of the event. One of QUEUED, HOLD, SUCCESSFUL, FAILED |
| response_status | number | null | Event status |
| error_code | string | null | None HTTP error code. |
| last_attempt_at | date | null | Date of the most recently attempted retry |
| next_attempt_at | date | null | Date of the next scheduled retry |
| sucessful_at | date | null | Date of the latest successful attempt |
| updated_at | date | Date the event was last updated | |
| created_at | date | Date the event was created |
JSON
{
"id": "evt_5b3mzbxk83deakr",
"team_id": "tm_5b3mzbxk83c0k7i",
"webhook_id": "web_5b3mzbxk83dcij0",
"source_id": "src_5b3mzbxk83dciin",
"destination_id": "des_5b3mzbxk83dciim",
"cli_id": null,
"event_data_id": "evtreq_Ixux8vb2VBnZIuieVFPcUF9d",
"attempts": 0,
"status": "QUEUED",
"response_status": null,
"last_attempt_at": null,
"next_attempt_at": null,
"successful_at": null,
"updated_at": "2020-03-22T18:24:01.031Z",
"created_at": "2020-03-22T18:24:01.035Z"
}
Retrieve all events
This endpoint lists all events, or a subset of events.
Filtering events
To filter the list of events, use only supported operators.
For example, append ?created_at[gte]=2021-10-12&created_at[lte]=2021-10-13 to retrieve events for that specific 24-hour period.
Including event data
To retrieve events with their data populated, use the ?include=data query parameter. Be aware that this can lead to very large responses.
Payload data exceeding 2.5 MB won't be returned, and data.body will be set to null. The request path, query and headers are still included.
To distinguish between these large payloads and payloads set to the JSON literal
null, leverageheaders['content-length'].
Including CLI events
CLI events are excluded from the results by default. To query CLI events, use /events?cli_id[any]=true.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string[] | Filter by event IDs |
| webhook_id | string[] | Filter by webhook connection IDs |
| source_id | string[] | Filter by source IDs |
| destination_id | string[] | Filter by destination IDs |
| cli_id | string[] | Filter by CLI IDs. ?[any]=true operator for any CLI. Defaults to null |
| status | string | Lifecyle status of the event. One of QUEUED, HOLD, SUCCESSFUL, FAILED |
| response_status | number | Filter by HTTP response status code |
| attempts | number | Filter by number of attempts |
| created_at | date | Filter by created_at date using a date operator |
| successful_at | date | Filter by last_attempt_at date using a date operator |
| last_attempt_at | date | Filter by last_attempt_at date using a date operator |
| next_attempt_at | date | Filter by next_attempt_at date using a date operator |
| body | JSON | URL Encoded string of the JSON to match to the data body |
| headers | JSON | URL Encoded string of the JSON to match to the data headers |
| parsed_query | JSON | URL Encoded string of the JSON to match to the parsed query (JSON representation of the query) |
| path | string | URL Encoded string of the string to match partially to the path |
| include | "data" | Include the data object in the event model |
| limit | string | Limit the returned event count (max 250) |
| order_by | string | Sort by created_at (default) or last_attempt_at. |
Endpoint
HTTP
GET /2022-10-01/eventsResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "evt_njCeMZHzNhJWdkkZ7PLCfEw5"
},
"count": 1,
"models": [
{
"id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
"attempts": 4,
"response_status": 422,
"last_attempt_at": "2021-08-02T13:52:16.439Z",
"next_attempt_at": null,
"successful_at": "2021-08-01T21:56:35.181Z",
"updated_at": "2021-08-02T13:52:16.813Z",
"created_at": "2021-08-01T21:44:57.513Z",
"status": "FAILED",
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"cli_id": null
}
]
}Retrieve an event
This endpoint retrieves a specific event.
The response contains the data object with the properties body and headers, representing the original data for that webhook request.
URL Parameter
| Parameter | Description |
|---|---|
| id | Event ID |
Endpoint
HTTP
GET /2022-10-01/events/:idResponse example
JSON
{
"id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
"attempts": 4,
"response_status": 422,
"last_attempt_at": "2021-08-02T13:52:16.439Z",
"next_attempt_at": null,
"successful_at": "2021-08-01T21:56:35.181Z",
"updated_at": "2021-08-02T13:52:16.813Z",
"created_at": "2021-08-01T21:44:57.513Z",
"status": "FAILED",
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"cli_id": null,
"data": {
"headers": {
"content-length": "20",
"x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
"cookie": "",
"x-client-version": "FirebaseCLI/undefined",
"content-type": "application/json",
"user-agent": "FirebaseCLI/undefined"
},
"body": {
"test": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
}Retry an event
This endpoint manually queues an event for retry.
URL Parameter
| Parameter | Description |
|---|---|
| id | Event ID |
Endpoint
HTTP
POST /2022-10-01/events/:id/retryResponse example
JSON
{
"event": {
"id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
"attempts": 4,
"response_status": 422,
"last_attempt_at": "2021-08-02T13:52:16.439Z",
"next_attempt_at": null,
"successful_at": "2021-08-01T21:56:35.181Z",
"updated_at": "2021-08-02T14:12:56.321Z",
"created_at": "2021-08-01T21:44:57.513Z",
"status": "QUEUED",
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"cli_id": null,
"data": {
"headers": {
"content-length": "20",
"x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
"cookie": "",
"x-client-version": "FirebaseCLI/undefined",
"content-type": "application/json",
"user-agent": "FirebaseCLI/undefined"
},
"body": {
"test": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
},
"attempt": {
"id": "atm_bfD1fTzCmj9nfiRNQ4j6YqHV",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"event_id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"response_status": null,
"successful_at": null,
"updated_at": "2021-08-02T14:12:56.319Z",
"created_at": "2021-08-02T14:12:56.353Z",
"error_code": null,
"bulk_retry_id": null,
"status": "QUEUED",
"trigger": "MANUAL",
"attempt_number": 5,
"delivered_at": null,
"responded_at": null,
"delivery_latency": null,
"response_latency": null,
"attemptResponse": null
}
}Mute an event
This endpoint cancels the next automatic retry.
URL Parameter
| Parameter | Description |
|---|---|
| id | Event ID |
The parameter
next_attempt_atis set tonull. This action is not reversible.
Endpoint
HTTP
PUT /2022-10-01/events/:id/muteResponse example
JSON
{
"id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
"attempts": 5,
"response_status": 422,
"last_attempt_at": "2021-08-02T13:52:16.439Z",
"next_attempt_at": null,
"successful_at": "2021-08-01T21:56:35.181Z",
"updated_at": "2021-08-02T14:12:56.466Z",
"created_at": "2021-08-01T21:44:57.513Z",
"status": "QUEUED",
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"cli_id": null,
"data": {
"headers": {
"content-length": "20",
"x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
"cookie": "",
"x-client-version": "FirebaseCLI/undefined",
"content-type": "application/json",
"user-agent": "FirebaseCLI/undefined"
},
"body": {
"test": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
}Attempts
An attempt is any request that Hookdeck makes on behalf of an event.
Endpoints
HTTP
GET /2022-10-01/attempts
GET /2022-10-01/attempts/:id
GET /2022-10-01/attempts
GET /2022-10-01/attempts/:idAttempt object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | Attempt ID | |
| team_id | string | Team ID | |
| event_id | string | Event ID | |
| response_status | number | null | Attempt's HTTP response code |
| successful_at | date | null | Date the attempt was successful |
| updated_at | date | Date the attempt was last updated | |
| created_at | date | Date the attempt was created | |
| error_code | string | Attempt could not complete because of an error | |
| bulk_retry_id | string | null | ID of associated bulk retry |
| status | string | Attempt status, one of PENDING, FAILED, SUCCESSFUL, QUEUED, HOLD | |
| trigger | string | How this attempt was triggered, one of INITIAL, MANUAL, BULK_RETRY, UNPAUSE, AUTOMATIC | |
| attempt_number | number | Sequential number of attempts (up to and including this one) made for the associated event | |
| delivered_at | date | null | Date the attempt was delivered |
| responded_at | date | null | Date the destination responded to this attempt |
| delivery_latency | number | null | Time elapsed between attempt initiation and final delivery (in ms) |
| response_latency | number | null | Time elapsed between attempt initiation and a response from the destination (in ms) |
| archived_at | date | null | Date the attempt was archived |
| body | string | null | Response body from the destination |
| requested_url | string | URL of the destination where delivery was attempted |
JSON
{
"id": "atm_12n4ffxk8adnqqj",
"team_id": "tm_5b3mzbxk83c0k7i",
"event_id": "evt_12n4ffxk8admulc",
"response_status": 200,
"successful_at": "2022-07-29T21:47:07.152Z",
"updated_at": "2022-07-29T21:47:07.154Z",
"created_at": "2022-07-29T21:47:06.816Z",
"error_code": null,
"bulk_retry_id": null,
"status": "SUCCESSFUL",
"trigger": "INITIAL",
"attempt_number": 1,
"delivered_at": "2022-07-29T21:47:07.052Z",
"responded_at": "2022-07-29T21:47:07.152Z",
"delivery_latency": 44,
"response_latency": 100,
"archived_at": null,
"body": "Accepted",
"requested_url": "https://mock.hookdeck.com"
}
Retrieve all attempts
This endpoint lists all attempts, or a subset of attempts.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| event_id | string[] | Event the attempt is associated with |
Endpoint
HTTP
GET /2022-10-01/attemptsResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "atm_NgrzbX4NcfazxAigdhb8KBXr"
},
"count": 1,
"models": [
{
"id": "atm_NgrzbX4NcfazxAigdhb8KBXr",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"event_id": "evt_vuHxr759DYe6LsBgDk2VOfqI",
"response_status": null,
"successful_at": null,
"updated_at": "2021-08-02T14:12:57.658Z",
"created_at": "2021-08-02T14:12:57.631Z",
"error_code": null,
"bulk_retry_id": null,
"status": "QUEUED",
"trigger": "INITIAL",
"attempt_number": 1,
"delivered_at": null,
"responded_at": null,
"delivery_latency": null,
"response_latency": null,
"archived_at": null
}
]
}Retrieve an attempt
This endpoint retrieves a specific attempt.
When retrieving a completed attempt, the response will contain the body of the destination's response.
URL Parameter
| Parameter | Description |
|---|---|
| id | Attempt ID |
Endpoint
HTTP
GET /2022-10-01/attempts/:idResponse example
JSON
{
"id": "atm_kgHSGmGMTXGfQhKArm77tRIp",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"event_id": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"response_status": 202,
"successful_at": "2021-08-01T21:56:35.181Z",
"updated_at": "2021-08-01T21:56:35.185Z",
"created_at": "2021-08-01T21:56:34.905Z",
"error_code": null,
"bulk_retry_id": null,
"status": "SUCCESSFUL",
"trigger": "MANUAL",
"attempt_number": 2,
"delivered_at": "2021-08-01T21:56:35.015Z",
"responded_at": "2021-08-01T21:56:35.181Z",
"delivery_latency": 110,
"response_latency": 166,
"archived_at": null,
"body": {
"message": "The Mock API returns the request data with a randomized status code",
"next_step": "Convinced? Update your destination with your own server HTTP URL.",
"mock_status": 202,
"requested_path": "/",
"received_data": {
"headers": {
"host": "mock.hookdeck.com",
"connection": "close",
"accept": "application/json, text/plain, */*",
"content-type": "application/json",
"idempotency-key": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
"cookie": "",
"x-client-version": "FirebaseCLI/undefined",
"user-agent": "FirebaseCLI/undefined",
"x-hookdeck-eventid": "evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"x-hookdeck-attempt-count": "2",
"x-hookdeck-event-url": "http://localhost:3000/events/evt_njCeMZHzNhJWdkkZ7PLCfEw5",
"x-hookdeck-signature": "Yhj7PMxNwFtNhZMQ6MFeLJsmC51li2aO4zanCwdld7I=",
"x-hookdeck-source-name": "shopify",
"x-newrelic-id": "VwQGVlRVDRAFVlJWBggGX1c=",
"x-newrelic-transaction": "PxQOWVRRAVBUAQUAUVVWVgACFB8EBw8RVU4aWwAKBgtQAVwFUwdXA1RSBENKQQ9SBgFQBw4AFTs=",
"x-request-id": "fed4b172-12f9-4a2d-b629-9de008b2e471",
"x-forwarded-for": "135.19.54.44",
"x-forwarded-proto": "https",
"x-forwarded-port": "443",
"via": "1.1 vegur",
"connect-time": "0",
"x-request-start": "1627854995250",
"total-route-time": "0",
"content-length": "20"
},
"body": {
"test": true
},
"query": {}
}
},
"requested_url": "https://mock.hookdeck.com/"
}Bulk retries
Endpoints
HTTP
GET /2022-10-01/bulk/events/retry
GET /2022-10-01/bulk/events/retry/:id
POST /2022-10-01/bulk/events/retry/:id/cancel
POST /2022-10-01/bulk/events/retry
GET /2022-10-01/bulk/events/retry/plan/generate
GET /2022-10-01/bulk/requests/retry
GET /2022-10-01/bulk/requests/retry/:id
POST /2022-10-01/bulk/requests/retry/:id/cancel
POST /2022-10-01/bulk/requests/retryBulk retry object
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the bulk retry |
| team_id | string | ID of the workspace |
| query | JSON | Query object to filter records |
| updated_at | date | Last time the bulk retry was updated |
| created_at | date | Date the bulk retry was created |
| completed_at | date | Date the bulk retry was completed |
| cancelled_at | date | Date the bulk retry was cancelled |
| estimated_batch | number | Number of batches required to complete the bulk retry |
| processed_batch | number | Number of batches currently processed |
| estimated_count | number | Number of estimated events to be retried |
| completed_count | number | Number of events that were successfully delivered |
| failed_count | number | Number of events that failed to be delivered |
| progress | number | Progression of the batch operations, values 0 - 1 |
| in_progress | boolean | Indicates if the bulk retry is currently in progress |
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.
Filter events using parameters of Events.
For example: ?query[status][0]=FAILED will include only events that failed, whereas ?query[status][0]=FAILED&query[status][0]=SUCCESSFUL will include events that both failed and succeeded.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string | Filter by bulk retry IDs |
| query | JSON | Filter 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 |
| cancelled_at | date | Filter by date the bulk retry was cancelled |
| completed_at | date | Filter by date the bulk retry completed |
| created_at | date | Filter by date the bulk retry was created |
| in_progress | boolean | Indicates if the bulk retry is currently in progress |
| limit | number | Limit the returned event count (max 250) |
Endpoint
HTTP
GET /2022-10-01/bulk/events/retryResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "blkret_95Vz4fYjIn5wgatOqX0kLRTH"
},
"count": 1,
"models": [
{
"id": "blkr_6dxoWIomd8DQdH",
"team_id": "tm_UkFg3CHYN50M",
"query": {
"status": [
"SUCCESSFUL"
]
},
"updated_at": "2022-05-13T09:06:03.983Z",
"created_at": "2022-05-13T09:05:55.394Z",
"completed_at": null,
"cancelled_at": "2022-05-13T09:06:03.982Z",
"estimated_batch": 4,
"processed_batch": 2,
"estimated_count": 28,
"completed_count": 8,
"failed_count": 0,
"number": 15,
"in_progress": false,
"progress": 0.29
}
]
}Retrieve a events bulk retry
This endpoint retrieves a specific bulk retry.
URL Parameter
| Parameter | Description |
|---|---|
| id | Bulk retry ID |
Endpoint
HTTP
GET /2022-10-01/bulk/events/retry/:idResponse example
JSON
{
"id": "blkr_6dxoWIomd8DQdH",
"team_id": "tm_UkFg3CHYN50M",
"query": {
"status": [
"SUCCESSFUL"
]
},
"updated_at": "2022-05-13T09:06:03.983Z",
"created_at": "2022-05-13T09:05:55.394Z",
"completed_at": null,
"cancelled_at": "2022-05-13T09:06:03.982Z",
"estimated_batch": 4,
"processed_batch": 2,
"estimated_count": 28,
"completed_count": 8,
"failed_count": 0,
"number": 15,
"in_progress": false,
"progress": 0.29
}Generate a events bulk retry plan
This endpoint estimates the number of events that will be retried with the given query parameters.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| query | JSON | Filter by the bulk retry events query object, use query parameters of Event |
Endpoint
HTTP
GET /2022-10-01/bulk/events/retry/planResponse example
JSON
{
"estimated_count": 301,
"estimated_batch": 2
}Create a events bulk retry
This endpoint creates a bulk retry.
Creating a bulk retry automatically begins the operation to retry any events matching the specified filters.
A bulk retry re-attempts delivery for one or more events, based on a filter.
Events on paused connections will still be retried unless excluded from the query.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| query | JSON | Filter properties for the events to be included in the bulk retry |
Endpoint
HTTP
POST /2022-10-01/bulk/events/retryRequest body example
JSON
{
"query": {
"source_id": [
"src_oDhfDrVAZV6OIPdBzcD97of2"
]
}
}Response example
JSON
{
"id": "blkr_6dxoWIomd8DQdH",
"team_id": "tm_UkFg3CHYN50M",
"query": {
"source_id": [
"src_oDhfDrVAZV6OIPdBzcD97of2"
]
},
"updated_at": "2022-05-13T09:06:03.983Z",
"created_at": "2022-05-13T09:05:55.394Z",
"completed_at": null,
"cancelled_at": "2022-05-13T09:06:03.982Z",
"estimated_batch": 4,
"processed_batch": 2,
"estimated_count": 28,
"completed_count": 8,
"failed_count": 0,
"number": 15,
"in_progress": false,
"progress": 0.29
}Cancel a events bulk retry
This endpoint stops a bulk retry if it's currently running.
URL Parameter
| Parameter | Description |
|---|---|
| id | Bulk retry ID |
Endpoint
HTTP
POST /2022-10-01/bulk/events/retry/:id/cancelResponse 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
}Retrieve all requests bulk retries
This endpoint lists all bulk retries, or a subset of bulk retries.
Filter events using parameters of Requests.
For example: ?query[rejection_cause][any]=true will include only requests that were rejected.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string | Filter by bulk retry IDs |
| query | JSON | Filter filter for events to be included in the bulk retry, use query parameters of Requests |
| query_partial_match | boolean | Allow partial filter match on query property |
| cancelled_at | date | Filter by date the bulk retry was cancelled |
| completed_at | date | Filter by date the bulk retry completed |
| created_at | date | Filter by date the bulk retry was created |
| in_progress | boolean | Indicates if the bulk retry is currently in progress |
| limit | number | Limit the returned event count (max 250) |
Endpoint
HTTP
GET /2022-10-01/bulk/requests/retryResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "blkret_95Vz4fYjIn5wgatOqX0kLRTH"
},
"count": 1,
"models": [
{
"id": "blkr_6dxoWIomd8DQdH",
"team_id": "tm_UkFg3CHYN50M",
"query": {
"rejection_cause": [
"SOURCE_ARCHIVED"
]
},
"updated_at": "2022-05-13T09:06:03.983Z",
"created_at": "2022-05-13T09:05:55.394Z",
"completed_at": null,
"cancelled_at": "2022-05-13T09:06:03.982Z",
"estimated_batch": 4,
"processed_batch": 2,
"estimated_count": 28,
"completed_count": 8,
"failed_count": 0,
"number": 15,
"in_progress": false,
"progress": 0.29
}
]
}Retrieve a requests bulk retry
This endpoint retrieves a specific bulk retry.
URL Parameter
| Parameter | Description |
|---|---|
| id | Bulk retry ID |
Endpoint
HTTP
GET /2022-10-01/bulk/requests/retry/:idResponse example
JSON
{
"id": "blkr_6dxoWIomd8DQdH",
"team_id": "tm_UkFg3CHYN50M",
"query": {
"rejection_cause": [
"SOURCE_ARCHIVED"
]
},
"updated_at": "2022-05-13T09:06:03.983Z",
"created_at": "2022-05-13T09:05:55.394Z",
"completed_at": null,
"cancelled_at": "2022-05-13T09:06:03.982Z",
"estimated_batch": 4,
"processed_batch": 2,
"estimated_count": 28,
"completed_count": 8,
"failed_count": 0,
"number": 15,
"in_progress": false,
"progress": 0.29
}Generate a requests bulk retry plan
This endpoint estimates the number of events that will be retried with the given query parameters.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| query | JSON | Filter by the bulk retry events query object, use query parameters of Event |
Endpoint
HTTP
GET /2022-10-01/bulk/requests/retry/planResponse example
JSON
{
"estimated_count": 301,
"estimated_batch": 2
}Create a requests bulk retry
This endpoint creates a bulk retry.
Creating a bulk retry automatically begins the operation to retry any events matching the specified filters.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| query | JSON | Filter properties for the events to be included in the bulk retry |
Endpoint
HTTP
POST /2022-10-01/bulk/requests/retryRequest body example
JSON
{
"query": {
"source_id": [
"src_oDhfDrVAZV6OIPdBzcD97of2"
]
}
}Response example
JSON
{
"id": "blkr_6dxoWIomd8DQdH",
"team_id": "tm_UkFg3CHYN50M",
"query": {
"rejection_cause": [
"SOURCE_ARCHIVED"
]
},
"updated_at": "2022-05-13T09:06:03.983Z",
"created_at": "2022-05-13T09:05:55.394Z",
"completed_at": null,
"cancelled_at": "2022-05-13T09:06:03.982Z",
"estimated_batch": 4,
"processed_batch": 2,
"estimated_count": 28,
"completed_count": 8,
"failed_count": 0,
"number": 15,
"in_progress": false,
"progress": 0.29
}Cancel a requests bulk retry
This endpoint stops a bulk retry if it's currently running.
URL Parameter
| Parameter | Description |
|---|---|
| id | Bulk retry ID |
Endpoint
HTTP
POST /2022-10-01/bulk/requests/retry/:id/cancelResponse example
JSON
{
"id": "blkr_6dxoWIomd8DQdH",
"team_id": "tm_UkFg3CHYN50M",
"query": {
"rejection_cause": [
"SOURCE_ARCHIVED"
]
},
"updated_at": "2022-05-13T09:06:03.983Z",
"created_at": "2022-05-13T09:05:55.394Z",
"completed_at": null,
"cancelled_at": "2022-05-13T09:06:03.982Z",
"estimated_batch": 4,
"processed_batch": 2,
"estimated_count": 28,
"completed_count": 8,
"failed_count": 0,
"number": 15,
"in_progress": false,
"progress": 0.29
}Bookmarks
A bookmark lets you conveniently store and replay a specific request.
Endpoints
HTTP
GET /2022-10-01/bookmarks
GET /2022-10-01/bookmarks/:id
POST /2022-10-01/bookmarks
PUT /2022-10-01/bookmarks/:id
POST /2022-10-01/bookmarks/:id/trigger
DELETE /2022-10-01/bookmarks/:idBookmark object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the bookmark | |
| team_id | string | ID of the workspace | |
| label | string | Descriptive name of the bookmark | |
| name | string | A unique, human-friendly name for the bookmark | |
| webhook_id | string | ID of the associated connection | |
| event_data_id | string | ID of the bookmarked event data | |
| last_used_at | date | null | Date the bookmark was last manually triggered |
| updated_at | date | Date the bookmark was last updated | |
| created_at | date | Date the bookmark was created |
JSON
{
"id": "bmk_zRQrmyGVDOEpPcwPqWjeI0p4",
"team_id": "tm_yUEO9119dsca8EgUE6qwXdCM",
"webhook_id": "web_EEHs0KX5hCL49NIN4GnCFG3Q",
"label": "Product Update – Out of Stock",
"name": null,
"event_data_id": "evtreq_3LtwaZwFBT8MYsWhqGSRlb7Q",
"last_used_at": "2021-04-29T03:46:32.390Z",
"updated_at": "2021-04-29T03:46:32.394Z",
"created_at": "2021-04-25T00:39:04.232Z",
"data": {
"headers": {
"content-type": "text/plain",
"content-length": "20"
},
"body": {
"example": true
}
}
}
Retrieve all bookmarks
This endpoint lists all bookmarks, or a subset of bookmarks.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string | Filter by bookmark IDs |
| name | string | Filter by bookmark name |
| webhook_id | string | Filter by associated connection ID |
| event_data_id | string | Filter by associated event data ID |
| label | string | Filter by label |
| last_used_at | date | Filter by last used date |
| limit | number | Limit the returned event count (max 250) |
Endpoint
HTTP
GET /2022-10-01/bookmarksResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1
},
"count": 0,
"models": []
}Retrieve a bookmark
This endpoint retrieves a specific bookmark.
URL Parameter
| Parameter | Description |
|---|---|
| id | Bookmark ID |
Endpoint
HTTP
GET /2022-10-01/bookmarks/:idResponse 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
| Parameter | Type | Description |
|---|---|---|
| label | string | Name of the bookmark |
| alias? | string | Alternate alias for the bookmark |
| webhook_id | string | ID of the associated connection |
| event_data_id | string | ID of the event data to bookmark |
Endpoint
HTTP
POST /2022-10-01/bookmarksRequest body example
JSON
{
"label": "Product Update – Out of Stock",
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp"
}Response example
JSON
{
"id": "bmk_pgmwVfQ9faN975poe0kW1Sp4",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"label": "Product Update – Out of Stock",
"alias": null,
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"last_used_at": null,
"updated_at": "2021-08-02T14:12:57.521Z",
"created_at": "2021-08-02T14:12:57.520Z",
"data": {
"headers": {
"content-length": "20",
"x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
"cookie": "",
"x-client-version": "FirebaseCLI/undefined",
"content-type": "application/json",
"user-agent": "FirebaseCLI/undefined"
},
"body": {
"test": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
}Update a bookmark
This endpoint updates a bookmark.
URL Parameter
| Parameter | Description |
|---|---|
| id | Bookmark ID |
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| label | string | Name of the bookmark |
| alias? | string | Alternate alias for the bookmark |
| webhook_id | string | ID of the associated connection |
| event_data_id | string | ID of the event data to bookmark |
Endpoint
HTTP
PUT /2022-10-01/bookmarks/:idRequest body example
JSON
{
"label": "Product Update – Out of Stock",
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp"
}Response example
JSON
{
"id": "bmk_4RbrZcXNALN6WKUljj92hY08",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"label": "Product Update – Out of Stock",
"alias": null,
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"last_used_at": null,
"updated_at": "2021-08-02T14:12:57.545Z",
"created_at": "2021-08-02T13:43:23.516Z",
"data": {
"headers": {
"content-length": "20",
"x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
"cookie": "",
"x-client-version": "FirebaseCLI/undefined",
"content-type": "application/json",
"user-agent": "FirebaseCLI/undefined"
},
"body": {
"test": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
}Trigger a bookmark
This endpoint uses a bookmark to create events.
Multiple events may be created, depending on the target. HTTP bookmarks will trigger at most one event, whereas CLI bookmarks will generate as many events as there are CLI clients listening to the associated connection.
URL Parameter
| Parameter | Description |
|---|---|
| id | Bookmark ID |
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| target? | string | cli or http |
The parameter
last_used_atis set to the current timestamp.
Endpoint
HTTP
POST /2022-10-01/bookmarks/:id/triggerResponse example
JSON
[
{
"id": "evt_vuHxr759DYe6LsBgDk2VOfqI",
"team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
"webhook_id": "web_UfM5ZY2wxLD6sLhDaKMcx5wp",
"source_id": "src_9YmY0SHklrv6zBQz78cKGwSW",
"destination_id": "des_fYYCay655IHwbOMhIaUXtNq2",
"attempts": 0,
"response_status": null,
"last_attempt_at": null,
"next_attempt_at": null,
"successful_at": null,
"updated_at": "2021-08-02T14:12:57.595Z",
"created_at": "2021-08-02T14:12:57.610Z",
"status": "QUEUED",
"event_data_id": "evtreq_HlJhb39nsjIP0FDsU3SY0fo7",
"cli_id": null,
"data": {
"headers": {
"content-length": "20",
"x-original-url": "/e/src_9YmY0SHklrv6zBQz78cKGwSW",
"cookie": "",
"x-client-version": "FirebaseCLI/undefined",
"content-type": "application/json",
"user-agent": "FirebaseCLI/undefined"
},
"body": {
"test": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
}
]Delete a bookmark
This endpoint deletes a bookmark.
Deleting a bookmark won't affect any events previously trigged by that bookmark.
URL Parameter
| Parameter | Description |
|---|---|
| id | Bookmark ID |
Endpoint
HTTP
DELETE /2022-10-01/bookmarks/:idResponse example
JSON
"bmk_4RbrZcXNALN6WKUljj92hY08"Issues
Issues let you track problems in your workspace and communicate resolution steps with your team.
Endpoints
HTTP
GET /2022-10-01/issues
GET /2022-10-01/issues/count
GET /2022-10-01/issues/:id
PUT /2022-10-01/issues/:id
DELETE /2022-10-01/issues/:idIssue object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the connection | |
| team_id | string | ID of the workspace | |
| type | string | Issue type | |
| status | string | OPENED | Current status, one of OPENED, ACKNOWLEDGED, RESOLVED, IGNORED |
| aggregation_keys | Object | The keys on which the issue is aggregated | |
| reference | Object | ID references to the object that opened the issue | |
| last_updated_by | string | null | ID of the team member who last updated the issue status |
| first_seen_at | string | ISO timestamp for when the issue was first opened | |
| last_seen_at | string | ISO timestamp for when the issue last occured | |
| dismissed_at | string | null | ISO timestamp for when the issue was dismissed |
| opened_at | string | ISO timestamp for when the issue was last opened | |
| updated_at | string | ISO timestamp for when the issue was last updated | |
| created_at | string | ISO timestamp for when the issue was created | |
| data | Object | Expended data of the reference object. Only populated when retrieving a single issue and not a list |
JSON
{
"id": "iss_GKcE4uWThIvClCI56edzJGMf",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"type": "delivery",
"status": "OPENED",
"aggregation_keys": {
"error_code": [],
"webhook_id": ["web_lo8z0VQZREANHxEwGJMUllAS"],
"response_status": [500]
},
"reference": {
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
},
"last_updated_by": null,
"merged_with": null,
"first_seen_at": "2022-03-13T16:05:26.856Z",
"last_seen_at": "2022-03-13T17:38:46.827Z",
"dismissed_at": null,
"opened_at": "2022-03-13T16:05:26.856Z",
"updated_at": "2022-03-13T17:38:46.827Z",
"created_at": "2022-03-13T16:05:26.856Z",
"data": {
"trigger_event": {
"id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"webhook_id": "web_lo8z0VQZREANHxEwGJMUllAS",
"source_id": "src_BBgENz5uR6YD5shCaBKawSGw",
"destination_id": "des_vINhNu8uG4OXHxKrhPwuiK89",
"attempts": 2,
"response_status": 422,
"last_attempt_at": "2022-03-13T16:07:52.171Z",
"next_attempt_at": null,
"successful_at": null,
"updated_at": "2022-03-13T16:07:52.314Z",
"created_at": "2022-03-13T16:05:26.304Z",
"status": "FAILED",
"event_data_id": "evtreq_auxUfCEIVhDwEaQHQnX1qcAy",
"cli_id": null,
"request": {
"headers": {
"content-length": "20",
"content-type": "application/json"
},
"body": {
"example": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
},
"trigger_attempt": {
"id": "atm_wAIWERIBzHWFTYJykqYPacVA",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"response_status": 500,
"successful_at": null,
"updated_at": "2022-03-13T16:05:26.749Z",
"created_at": "2022-03-13T16:05:26.318Z",
"error_code": null,
"bulk_retry_id": null,
"status": "FAILED",
"trigger": "INITIAL",
"attempt_number": 1,
"delivered_at": "2022-03-13T16:05:26.597Z",
"responded_at": "2022-03-13T16:05:26.747Z",
"delivery_latency": 279,
"response_latency": 150,
"archived_at": null,
"body": {
"example": true
},
"requested_url": "https://mock.hookdeck.com/?status=random"
}
}
}
Retrieve all issues
This endpoint lists all issues, or a subset of issues.
Dismissed issues are filtered out by default.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string | Filter by issue IDs |
| type | string | The issue type |
| status | string | The issue status |
| merged_with | string | The issue ID it was merged with |
| aggregation_keys | json | JSON that will evaluate has a partial match of issue aggregation_keys |
| created_at | date | Date the issues were created |
| first_seen_at | date | Date the issues were first seen |
| last_seen_at | date | Date the issues were last seen |
| dismissed_at | date | Date the issues were dismissed |
| opened_at | date | Date the issues were opened |
| order_by | string | The date property to order by |
| dir | string | The ordering direction |
| limit | number | Limit the returned model count (max 250) |
Endpoint
HTTP
GET /2022-10-01/issuesResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 1,
"next": "iss_GKcE4uWThIvClCI56edzJGMf"
},
"count": 1,
"models": [
{
"id": "iss_GKcE4uWThIvClCI56edzJGMf",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"type": "delivery",
"status": "OPENED",
"aggregation_keys": {
"error_code": [],
"webhook_id": [
"web_lo8z0VQZREANHxEwGJMUllAS"
],
"response_status": [
500
]
},
"reference": {
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
},
"last_updated_by": null,
"merged_with": null,
"first_seen_at": "2022-03-13T16:05:26.856Z",
"last_seen_at": "2022-03-13T17:38:46.827Z",
"dismissed_at": null,
"opened_at": "2022-03-13T16:05:26.856Z",
"updated_at": "2022-03-13T17:38:46.827Z",
"created_at": "2022-03-13T16:05:26.856Z"
}
]
}Count issues
This endpoint counts all issues, or a subset of issues.
Dismissed issues are filtered out by default.
Query Parameter
| Parameter | Type | Description |
|---|---|---|
| id | string | Filter by issue IDs |
| type | string | The issue type |
| status | string | The issue status |
| merged_with | string | The issue ID it was merged with |
| aggregation_keys | json | JSON that will evaluate has a partial match of issue aggregation_keys |
| created_at | date | Date the issues were created |
| first_seen_at | date | Date the issues were first seen |
| last_seen_at | date | Date the issues were last seen |
| dismissed_at | date | Date the issues were dismissed |
| opened_at | date | Date the issues were opened |
| order_by | string | The date property to order by |
| dir | string | The ordering direction |
| limit | number | Limit the returned model count (max 250) |
Endpoint
HTTP
GET /2022-10-01/issues/countResponse example
JSON
10Retrieve an issue
This endpoint retrieves a specific issue.
URL Parameter
| Parameter | Description |
|---|---|
| id | Issue ID |
Endpoint
HTTP
GET /2022-10-01/issues/:idResponse example
JSON
{
"id": "iss_GKcE4uWThIvClCI56edzJGMf",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"type": "delivery",
"status": "OPENED",
"aggregation_keys": {
"error_code": [],
"webhook_id": [
"web_lo8z0VQZREANHxEwGJMUllAS"
],
"response_status": [
500
]
},
"reference": {
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
},
"last_updated_by": null,
"merged_with": null,
"first_seen_at": "2022-03-13T16:05:26.856Z",
"last_seen_at": "2022-03-13T17:38:46.827Z",
"dismissed_at": null,
"opened_at": "2022-03-13T16:05:26.856Z",
"updated_at": "2022-03-13T17:38:46.827Z",
"created_at": "2022-03-13T16:05:26.856Z",
"data": {
"trigger_event": {
"id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"webhook_id": "web_lo8z0VQZREANHxEwGJMUllAS",
"source_id": "src_BBgENz5uR6YD5shCaBKawSGw",
"destination_id": "des_vINhNu8uG4OXHxKrhPwuiK89",
"attempts": 2,
"response_status": 422,
"last_attempt_at": "2022-03-13T16:07:52.171Z",
"next_attempt_at": null,
"successful_at": null,
"updated_at": "2022-03-13T16:07:52.314Z",
"created_at": "2022-03-13T16:05:26.304Z",
"status": "FAILED",
"event_data_id": "evtreq_auxUfCEIVhDwEaQHQnX1qcAy",
"cli_id": null,
"request": {
"headers": {
"content-length": "20",
"content-type": "application/json"
},
"body": {
"example": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
},
"trigger_attempt": {
"id": "atm_wAIWERIBzHWFTYJykqYPacVA",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"response_status": 500,
"successful_at": null,
"updated_at": "2022-03-13T16:05:26.749Z",
"created_at": "2022-03-13T16:05:26.318Z",
"error_code": null,
"bulk_retry_id": null,
"status": "FAILED",
"trigger": "INITIAL",
"attempt_number": 1,
"delivered_at": "2022-03-13T16:05:26.597Z",
"responded_at": "2022-03-13T16:05:26.747Z",
"delivery_latency": 279,
"response_latency": 150,
"archived_at": null,
"body": {
"example": true
},
"requested_url": "https://mock.hookdeck.com/?status=random"
}
}
}Update an issue
This endpoint updates an issue's status.
URL Parameter
| Parameter | Description |
|---|---|
| id | Issue ID |
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| status | string | The new issue status |
Endpoint
HTTP
PUT /2022-10-01/issues/:idRequest body example
JSON
{
"status": "RESOLVED"
}Response example
JSON
{
"id": "iss_GKcE4uWThIvClCI56edzJGMf",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"type": "delivery",
"status": "RESOLVED",
"aggregation_keys": {
"error_code": [],
"webhook_id": [
"web_lo8z0VQZREANHxEwGJMUllAS"
],
"response_status": [
500
]
},
"reference": {
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
},
"last_updated_by": "tmem_Mus4DfdnV4kKepu6W0PKGYMR",
"merged_with": null,
"first_seen_at": "2022-03-13T16:05:26.856Z",
"last_seen_at": "2022-03-13T17:38:46.827Z",
"dismissed_at": null,
"opened_at": "2022-03-13T16:05:26.856Z",
"updated_at": "2022-03-13T17:38:46.827Z",
"created_at": "2022-03-13T16:05:26.856Z",
"data": {
"trigger_event": {
"id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"webhook_id": "web_lo8z0VQZREANHxEwGJMUllAS",
"source_id": "src_BBgENz5uR6YD5shCaBKawSGw",
"destination_id": "des_vINhNu8uG4OXHxKrhPwuiK89",
"attempts": 2,
"response_status": 422,
"last_attempt_at": "2022-03-13T16:07:52.171Z",
"next_attempt_at": null,
"successful_at": null,
"updated_at": "2022-03-13T16:07:52.314Z",
"created_at": "2022-03-13T16:05:26.304Z",
"status": "FAILED",
"event_data_id": "evtreq_auxUfCEIVhDwEaQHQnX1qcAy",
"cli_id": null,
"request": {
"headers": {
"content-length": "20",
"content-type": "application/json"
},
"body": {
"example": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
},
"trigger_attempt": {
"id": "atm_wAIWERIBzHWFTYJykqYPacVA",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"response_status": 500,
"successful_at": null,
"updated_at": "2022-03-13T16:05:26.749Z",
"created_at": "2022-03-13T16:05:26.318Z",
"error_code": null,
"bulk_retry_id": null,
"status": "FAILED",
"trigger": "INITIAL",
"attempt_number": 1,
"delivered_at": "2022-03-13T16:05:26.597Z",
"responded_at": "2022-03-13T16:05:26.747Z",
"delivery_latency": 279,
"response_latency": 150,
"archived_at": null,
"body": {
"example": true
},
"requested_url": "https://mock.hookdeck.com/?status=random"
}
}
}Dismiss an issue
This endpoint marks an issue as dismissed.
URL Parameter
| Parameter | Description |
|---|---|
| id | Connection ID |
The parameter
dimissed_atis set to the current timestamp.
Endpoint
HTTP
DELETE /2022-10-01/issues/:idResponse example
JSON
{
"id": "iss_GKcE4uWThIvClCI56edzJGMf",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"type": "delivery",
"status": "RESOLVED",
"aggregation_keys": {
"error_code": [],
"webhook_id": [
"web_lo8z0VQZREANHxEwGJMUllAS"
],
"response_status": [
500
]
},
"reference": {
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"attempt_id": "atm_wAIWERIBzHWFTYJykqYPacVA"
},
"last_updated_by": "tmem_Mus4DfdnV4kKepu6W0PKGYMR",
"merged_with": null,
"first_seen_at": "2022-03-13T16:05:26.856Z",
"last_seen_at": "2022-03-13T17:38:46.827Z",
"dismissed_at": "2022-03-15T16:05:26.856Z",
"opened_at": "2022-03-13T16:05:26.856Z",
"updated_at": "2022-03-13T17:38:46.827Z",
"created_at": "2022-03-13T16:05:26.856Z",
"data": {
"trigger_event": {
"id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"webhook_id": "web_lo8z0VQZREANHxEwGJMUllAS",
"source_id": "src_BBgENz5uR6YD5shCaBKawSGw",
"destination_id": "des_vINhNu8uG4OXHxKrhPwuiK89",
"attempts": 2,
"response_status": 422,
"last_attempt_at": "2022-03-13T16:07:52.171Z",
"next_attempt_at": null,
"successful_at": null,
"updated_at": "2022-03-13T16:07:52.314Z",
"created_at": "2022-03-13T16:05:26.304Z",
"status": "FAILED",
"event_data_id": "evtreq_auxUfCEIVhDwEaQHQnX1qcAy",
"cli_id": null,
"request": {
"headers": {
"content-length": "20",
"content-type": "application/json"
},
"body": {
"example": true
},
"query": "",
"parsed_query": {},
"path": "/"
}
},
"trigger_attempt": {
"id": "atm_wAIWERIBzHWFTYJykqYPacVA",
"team_id": "tm_eSRQYT4zriOhHcVtvIKvHlzf",
"event_id": "evt_G5cAJXite5XJ65n7eVpQ9GsR",
"response_status": 500,
"successful_at": null,
"updated_at": "2022-03-13T16:05:26.749Z",
"created_at": "2022-03-13T16:05:26.318Z",
"error_code": null,
"bulk_retry_id": null,
"status": "FAILED",
"trigger": "INITIAL",
"attempt_number": 1,
"delivered_at": "2022-03-13T16:05:26.597Z",
"responded_at": "2022-03-13T16:05:26.747Z",
"delivery_latency": 279,
"response_latency": 150,
"archived_at": null,
"body": {
"example": true
},
"requested_url": "https://mock.hookdeck.com/?status=random"
}
}
}Notifications
Notifications let your team receive alerts anytime an issue changes.
Webhook Notifications
This endpoint enables or disables webhook notifications for the workspace.
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| enabled | boolean | Enable or disable webhook notifications on the workspace |
| source_id | string | The Hookdeck Source to send the webhook to |
| topics | string[] | List of topics to send notifications for |
Supported Topics
issue.openedissue.updated
Endpoint
HTTP
PUT /2022-10-01/notifications/webhooksResponse example
JSON
{
"enabled": true,
"topics": [
"issue.opened"
],
"source_id": "src_9YmY0SHklrv6zBQz78cKGwSW"
}Integrations
An integration configures platform-specific behaviors, such as signature verification.
Endpoints
HTTP
GET /2022-10-01/integrations
GET /2022-10-01/integrations/:id
POST /2022-10-01/integrations
PUT /2022-10-01/integrations/:id
DELETE /2022-10-01/integrations/:id
PUT /2022-10-01/integrations/:id/attach/:source_id
PUT /2022-10-01/integrations/:id/deattach/:source_idIntegration object
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | ID of the integration | |
| team_id | string | ID of the workspace | |
| label | string | Label of the integration | |
| provider | string | The provider name (see provider list below) | |
| features | string[] | List of features to enable (see features list below) | |
| configs | object | Decrypted Key/Value object of the associated configuration for that provider | |
| sources | string[] | List of source IDs the integration is attached to | |
| updated_at | date | Date the source was last updated | |
| created_at | date | Date the source was created |
Providers and features
| Feature | Behavior |
|---|---|
VERIFICATION | Enable authenticity verification when a request is received by Hookdeck. If the request is not authentic, it will be ignored and not create an event. |
HANDSHAKE | Enable handshake (or URL validation) for platforms that require it, and use a unique value to perform the handshake. |
POLLING | PREVIEW ONLY. Enable automatic polling and reconciliation. |
Supported features by provider
Each provider has a set of available features. Additionally, each feature requires a set of Key/Value configuration parameters that need to be defined as part of the configs object.
| Provider | Features | Config Keys |
|---|---|---|
HANDSHAKE | api_key | |
| recharge | VERIFICATION | webhook_secret_key |
| stripe | VERIFICATION | webhook_secret_key |
| shopify | VERIFICATION | webhook_secret_key |
| shopify | POLLING | Contact us |
| github | VERIFICATION | webhook_secret_key |
| postmark | VERIFICATION | webhook_secret_key |
Supported features for generic configurations
Generic configurations let you add support for providers that are not explicitly supported.
| Generic | Features | Config Keys |
|---|---|---|
| hmac | VERIFICATION | algorithm, encoding, header_key, webhook_secret_key |
| basic_auth | VERIFICATION | name, password |
| api_key | VERIFICATION |
Supported values for generic HMAC keys
The following value types are supported for generic HMAC implementations.
| Key | Supported values |
|---|---|
algorithm | sha256, sha512, sha1, md5 |
encoding | hex, base64 |
JSON
{
"id": "int_9wnkSCsbk8nPOy",
"team_id": "tm_AkLVUIfTy4nn",
"label": "Shopify",
"provider": "shopify",
"updated_at": "2022-06-13T13:27:16.822Z",
"created_at": "2022-06-13T13:27:16.821Z",
"features": ["VERIFICATION"],
"sources": [],
"configs": {
"webhook_secret_key": "your-secret"
}
}
Retrieve all integrations
This endpoint lists all integrations.
Endpoint
HTTP
GET /2022-10-01/integrationsResponse example
JSON
{
"pagination": {
"order_by": "created_at",
"dir": "desc",
"limit": 100
},
"count": 1,
"models": [
{
"id": "int_9wnkSCsbk8nPOy",
"team_id": "tm_AkLVUIfTy4nn",
"label": "Shopify",
"provider": "shopify",
"updated_at": "2022-06-13T13:27:16.822Z",
"created_at": "2022-06-13T13:27:16.821Z",
"features": [
"VERIFICATION"
],
"sources": [],
"configs": {
"webhook_secret_key": "your-secret"
}
}
]
}Retrieve an integration
This endpoint retrieves a specific integration.
URL Parameter
| Parameter | Description |
|---|---|
| id | Integration ID |
Endpoint
HTTP
GET /2022-10-01/integrations/:idResponse example
JSON
{
"id": "int_9wnkSCsbk8nPOy",
"team_id": "tm_AkLVUIfTy4nn",
"label": "Shopify",
"provider": "shopify",
"updated_at": "2022-06-13T13:27:16.822Z",
"created_at": "2022-06-13T13:27:16.821Z",
"features": [
"VERIFICATION"
],
"sources": [],
"configs": {
"webhook_secret_key": "your-secret"
}
}Create an integration
This endpoint creates an integration.
Body Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| label | string | Label of the integration | |
| provider | string | The provider name (see provider list above) | |
| features | string[] | List of features to enable (see features list above) | |
| configs | object | Decrypted Key/Value object of the associated configuration for that provider |
Endpoint
HTTP
POST /2022-10-01/integrationsRequest body example
JSON
{
"label": "Shopify",
"configs": {
"webhook_secret_key": "your-secret"
},
"provider": "shopify",
"features": [
"VERIFICATION"
]
}Response example
JSON
{
"id": "int_XMx4wvW0luLTb4",
"team_id": "tm_AkLVUIfTy4nn",
"label": "Shopify",
"provider": "shopify",
"updated_at": "2022-06-13T13:28:24.794Z",
"created_at": "2022-06-13T13:28:24.793Z",
"features": [
"VERIFICATION"
],
"sources": [],
"configs": {
"webhook_secret_key": "your-secret"
}
}Update an integration
This endpoint updates an integration.
Body Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| label | string | Label of the integration | |
| provider | string | The provider name (see provider list above) | |
| features | string[] | List of features to enable (see features list above) | |
| configs | object | Decrypted Key/Value object of the associated configuration for that provider |
Endpoint
HTTP
PUT /2022-10-01/integrations/:idRequest body example
JSON
{
"configs": {
"webhook_secret_key": "your-new-secret"
}
}Response example
JSON
{
"id": "int_XMx4wvW0luLTb4",
"team_id": "tm_AkLVUIfTy4nn",
"label": "Shopify",
"provider": "shopify",
"updated_at": "2022-06-13T13:28:24.794Z",
"created_at": "2022-06-13T13:28:24.793Z",
"features": [
"VERIFICATION"
],
"sources": [],
"configs": {
"webhook_secret_key": "your-new-secret"
}
}Delete an integration
This endpoint deletes an integration.
URL Parameter
| Parameter | Description |
|---|---|
| id | Integration ID |
Endpoint
HTTP
DELETE /2022-10-01/integrations/:idResponse example
JSON
"int_9wnkSCsbk8nPOy"Attach an integration to a source
This endpoint attaches an integration to a source
URL Parameter
| Parameter | Description |
|---|---|
| id | Integration ID |
| source_id | Source ID |
Endpoint
HTTP
PUT /2022-10-01/integrations/:id/attach/:source_idResponse example
JSON
trueDetatch an integration to a source
This endpoint detaches an integration from a source
URL Parameter
| Parameter | Description |
|---|---|
| id | Integration ID |
| source_id | Source ID |
Endpoint
HTTP
PUT /2022-10-01/integrations/:id/detach/:source_idResponse example
JSON
trueRule
A rule can be applied to either a Ruleset or a Connection using the rules field.
Retry
The retry rule determines the rate and limit of automatic retries on failed events.
| Property | Type | Description |
|---|---|---|
| type | retry | A retry rule must be of type retry |
| strategy | linear exponential | Algorithm to use when calculating delay between retries |
| count | number | Maximum number of retries to attempt |
| interval | number | Time in MS between each retry |
JSON
{
"type": "retry",
"strategy": "linear",
"count": 5,
"interval": 60000
}
Alert
The alert rule determines when Hookdeck will trigger new issues for failed events.
| Property | Type | Description |
|---|---|---|
| type | alert | A alert rule must be of type alert |
| strategy | each_attempt last_attempt | Strategy to use when deciding to trigger an issue |
JSON
{
"type": "alert",
"strategy": "each_attempt"
}
Delay
The delay rule allows you to introduce a delay between the moment Hookdeck receives an avent, and when it's forwarded to your destination.
| Property | Type | Description |
|---|---|---|
| type | delay | A delay rule must be of type delay |
| delay | number | Delay to introduce in MS |
JSON
{
"type": "delay",
"delay": 1000
}
Filter
The filter rule allows you to permit and route webhooks conditionally based on the contents of their Headers, Body, Query, and/or Path.
For more information on how to set up filters, including syntax, review our filter documentation.
| Property | Type | Description |
|---|---|---|
| type | filter | A filter rule must be of type filter |
| body? | JSON | JSON using our filter syntaxt to filter on request body |
| headers? | JSON | JSON using our filter syntaxt to filter on request headers |
| path? | JSON | JSON using our filter syntaxt to filter on request path |
| query? | JSON | JSON using our filter syntaxt to filter on request parsed query params |
JSON
{
"type": "filter",
"body": {
"example": true
}
}
Get In Touch
Reach out using the live chat in the bottom right corner, or our contact form.