Getting Started
The Hookdeck REST API allows you to set up connections, retrieve events, and perform actions programmatically.
Get an API key
You'll need to include an API key in every API request. If you do not yet have a Hookdeck account, please sign up for a free account. Your API key is located in your project settings.
To include your API key in requests, use either Bearer Token Authentication or Basic Authentication.
Method | Procedure |
---|---|
Bearer Token Authentication | Include the header Authorization: Bearer $API_KEY , replacing $API_KEY with your personal key |
Basic Authentication | Set the username as your API key, and supply an empty password |
Create your first connection
Creating your first connection will allow you to start routing events with Hookdeck.
The API only supports
application/json
for both input and output. Header is optional.
Required parameters
Parameter | Type | Description |
---|---|---|
name | string | Name of the new connection |
source.name | string | Name of the source to create |
destination.name | string | Name of the destination to create |
destination.url | string | HTTP endpoint of the destination |
destination.cli_path | string | Path for the CLI destination |
Only one of
url
orcli_path
is required.
Response
The response body returns objects for the associated source, destination, and ruleset.
These resources can be reused in future requests by passing the destination_id
, source_id
, or ruleset_id
instead of an object.
Verify your first connection
Verifying the connection lets you know Hookdeck is properly ingesting and processing events from your source.
Copy the unique Hookdeck URL and paste it into your API provider's HTTP URL field. Test the connection by triggering a request on your source. As soon Hookdeck receives your first request, it'll appear in your dashboard.
The connection URL is a property of the source object.
Congratulations! Your request & events can now be viewed, inspected, filtered, sorted, retried, and more using Hookdeck.
Authentication
Your API key is located in your project settings, and must be included in every API request. Use either Bearer Token Authentication or Basic Authentication.
Method | Procedure |
---|---|
Bearer Token Authentication | Include the header Authorization: Bearer $API_KEY , replacing $API_KEY with your project key |
Basic Authentication | Set the username as your API key, and supply an empty password |
Paging
All GET
endpoints that retrieve a list of resources are paged using cursor (aka keyset) pagination, which resides in the response body's pagination
object.
Parameter | Default | Description |
---|---|---|
order_by | "created_at" | The sortable key to use (options varies base on the resource ) |
dir | "desc" | The direction to sort it ("asc" or "desc" ) |
limit | 100 | The making amount of results returned per query (max: 250 ) |
next | undefined | The ID to provide in the query to get the next set of results |
prev | undefined | The ID to provide in the query to get the previous set of results |
Unless you have specified an order_by
or dir
, you can omit it from the next or previous set query. You only have to carry them over if you are not using the resource default.
Errors
Hookdeck uses standard HTTP response codes to indicate the success or failure of an API request.
Parameter | Type | Description |
---|---|---|
handle | boolean | Error was handled by the API and did not resolve in an uncaught exception |
status | integer | HTTP status code for the error |
message | string | Any message associated with the error |
data | object | Any data related to the error, useful for diagnostics |
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error. See a more complete list of error codes here.
Rate Limits
The Hookdeck API has a rate limit of 240 request per minute, per API key. Contact us if you need your rate limit increased.
Query Formatting
Arrays
Arrays in query parameters are indicated by a []
appended to their type, like string[]
.
For example: ?item[1]=hello&item[2]=world
becomes ["hello", "world"]
Date
Dates are expected in ISO format.
For example: 2021-01-21T20:16:28Z
or 2021-01-21
JSON
Some query parameters take JSON as input. The JSON should be stringified and URL encoded.
For example: ?body=%7B%0A%20%20"hello"%3A%20"world"%0A%7D
becomes { "hello": "world" }
Operators
Most GET
endpoints that retrieve a list of resources support operators as part of the request query.
For example: ?number[gte]=1&number[lte]=10
Operator | Supported Types | Description |
---|---|---|
gte | date number | Greater than or equal to |
gt | date number | Greater than |
lte | date number | Lesser than or equal to |
lt | date number | Lesser than |
any | date number string | Not null |
contains | string | Contains |
Changelog
When backwards-incompatible changes are made to the API, a new, dated version is released. The latest version is 2024-09-01.
The API version can be set in the base path of any endpoint, such as https://api.hookdeck.com/2024-09-01/sources. Otherwise the API defaults to the oldest supported version.
The backwards-incompatible changes for each version are listed below. Backwards-compatible changes don’t need a new API version and do not appear in this list.
Dated versions remain supported for up to 1 year after the date of release. For instance 2023-07-01 will be officially supported until 2024-07-01.
2024-09-01
Change to attempts
Attempts no longer store state and are created when the event is delivered rather then when the event is queued for delivery.
Because of the underlying data structure change, the behavior of the API has changed for some endpoint, regardless of versions. While those are not technically breaking changes, they are worth noting:
- The
/attempts
(see: Retrieve all attempts) endpoint now only returns attempts with status ofSUCCESFUL
orFAILED
. This is true regardless of API version. - The
/events/:id/retry
will always returnnull
for theattempt
property on the response. This is true regardless of API version.
The breaking changes for this version specifically are:
- The
/events/:id/retry
(see: Retry an event) endpoint previously returned{ event: Event, attempt: Attempt }
and now only returns the Event object in root of the response.
2024-03-01
Renamed archive to disable
On Source, Destination and Connection objects, archive
and unarchive
have been renamed as disabled
and enable
. This affects the following:
archived_at
has been renamed todisabled_at
/sources/:id/archive
have been renamed to/sources/:id/disable
(see Disable a source)/sources/:id/unarchive
have been renamed to/sources/:id/enable
(see Enable a source)/connections/:id/archive
have been renamed to/connections/:id/disable
(see Disable a connection)/connections/:id/unarchive
have been renamed to/connections/:id/enable
(see Enable a connection)/destinations/:id/archive
have been renamed to/destinations/:id/disable
(see Disable a destination)/destinations/:id/unarchive
have been renamed to/destinations/:id/enable
(see Enable a destination)- Ignored event cause
ARCHIVED
has been renamed asDISABLED
- Rejection cause
SOURCE_ARCHIVED
has been renamed asSOURCE_DISABLED
Standardise source verification configs
To use consistent casing and keys between source authentication and destination authentication, we have made the following changes:
- On the Source's verification, rename
user
asusername
in the following config types:- Basic Auth
- Postmark
- Pipedrive
- All config types have been uppercased on the Source's verification. For instance,
hmac
is renamed asHMAC
,github
is renamed asGITHUB
and so on
2023-07-01
Removing rulesets
Removes support for Rulesets and is replaced by setting rules directly on connections.
- Removed
rulesets
object andresolved_rules
array from Connections. - Removed all
/rulesets
endpoints - Removed
ruleset
andruleset_id
property when creating or updating a Connection
Replacing integrations by Source "verification"
- Add the
verification
property to the Source model - Add the
verification
input when creating or updating a Source - Remove the
integration
andintegration_id
property from Source - Removed all
/integrations
endpoints
Integrations no longer need to be created and managed independantly from the source it's attached to. Instead you should pass the verification property to the source directly.
2023-01-01
- Removed
alert
rule type fromrules
on Rulesets and Connections.
2022-11-01 [DEPRECATED]
- Changed the
string
responses of DELETE operations on /bookmarks/:id and /integrations/:id to{ "id": "SOME_ID" }
instead ofID
to prevent error with unstructured response with some clients. - Changed the
boolean
responses of PUT operations on /integrations/:id/attach/:source_id and /integrations/:id/detach/:source_id to{ "success": true }
instead oftrue
to prevent error with unstructured response with some clients. - Changed the
number
responses of GET operations on /issues/count to{ "count": 123 }
instead of123
to prevent error with unstructured response with some clients.
2022-10-01 [DEPRECATED]
- Remove the properties
completed_event_id
andlast_processed_event_id
from the Event Bulk Retry model - Renamed the following properties on the Event Bulk Retry model
estimated_batch_count
toestimated_batch
processed_batch_count
toprocessed_batch
estimated_event_count
toestimated_count
delivered_event_count
tocompleted_count
failed_event_count
tofailed_count
- Added bulk retries for
requests
2022-07-01 [DEPRECATED]
- Renamed the
request
property todata
on Events and Bookmarks - Renamed the
request
value todata
when querying events with the data included, such that/events?include=request
is now/events?include=data
- Renamed the
event_request_id
property on Events and Bookmarks toevent_data_id
2022-03-01 [DEPRECATED]
- Removed the
interval
property from the Alert rule. Alert rule now controls how new issues are opened and notifications are now triggered by an issue opening or re-opening.
2021-08-01 [DEPRECATED]
- Removed the
label
property for Sources, Destinations, Rulesets and Connections. - Renamed the
alias
property toname
for Sources, Destinations, Rulesets and Connections. - Removed the
alert_strategy
andalert_interval
property for Rulesets. - Removed the
retry_strategy
,retry_interval
andretry_count
property for Rulesets. - Removed the
filters
property for Connections. - Added the
rules
property to Connections and Rulesets.
Introducing Rules
The removed properties of Rulesets and Connections have been replaced by the rules
array. Each rule has a type
and a set of properties to configure its behavior. Rule definitions are here.
2020-01-01 [DEPRECATED]
2020-01-01 marks the intial released of the API.
OpenAPI Schema
Our OpenAPI schema is available at https://api.hookdeck.com/2024-09-01/openapi.
OpenAPI schemas can be used to generate SDKs for your language of choice and work with various tools made for OpenAPI definitions such as importing into Postman.
We provide SDKs for both TypeScript and Go.
Connections
A connection lets you route events from a source to a destination.
Connections were historically called "webhooks". The endpoint root path
/webhooks
has been moved to/connections
. The former will remain functional, but consider migrating to/connections
.
Connection object
id
string
ID of the connection
name
string
Unique name of the connection for this source
full_name
string
Full name of the connection concatenated from source, connection and desitnation name
description
string
Description of the connection
team_id
string
ID of the project
destination
Destination
Associated Destination object
source
Source
Associated Source object
rules
Rule[]
Array of rules configured on the connection
paused_at
string
Date the connection was paused
updated_at
string
Date the connection was last updated
created_at
string
Date the connection was created
archived_at
string
Date the connection was archived
resolved_rules
Rule[]
Array of rules to apply
ruleset
Ruleset
Associated Ruleset object
Retrieve all connections
This endpoint lists all connections, or a subset of connections.