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.

MethodProcedure
Bearer Token AuthenticationInclude the header Authorization: Bearer $API_KEY, replacing $API_KEY with your personal key
Basic AuthenticationSet the username as your API key, and supply an empty password

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

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

Only one of url or cli_path is required.

Response

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

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

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.

MethodProcedure
Bearer Token AuthenticationInclude the header Authorization: Bearer $API_KEY, replacing $API_KEY with your project key
Basic AuthenticationSet 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.

ParameterDefaultDescription
order_by"created_at"The sortable key to use (options varies base on the resource )
dir"desc"The direction to sort it ("asc" or "desc")
limit100The making amount of results returned per query (max: 250)
nextundefinedThe ID to provide in the query to get the next set of results
prevundefinedThe ID to provide in the query to get the previous set of results

Unless you have specified an order_by or dir, you can omit it from the next or previous set query. You only have to carry them over if you are not using the resource default.

Errors

Hookdeck uses standard HTTP response codes to indicate the success or failure of an API request.

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

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error. See a more complete list of error codes here.

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

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

Changelog

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

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

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

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

2024-09-01

Change to attempts

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

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

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

The breaking changes for this version specifically are:

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

2024-03-01

Renamed archive to disable

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

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

Standardise source verification configs

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

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

2023-07-01

Removing rulesets

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

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

Replacing integrations by Source "verification"

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

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

2023-01-01

  • Removed alert rule type from rules on Rulesets and Connections.

2022-11-01 [DEPRECATED]

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

2022-10-01 [DEPRECATED]

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

2022-07-01 [DEPRECATED]

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

2022-03-01 [DEPRECATED]

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

2021-08-01 [DEPRECATED]

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

Introducing Rules

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

2020-01-01 [DEPRECATED]

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

OpenAPI Schema

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

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

We provide SDKs for both TypeScript and Go.

Connections

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

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

Connection object

id

string
Required

ID of the connection

name

string
Required

Unique name of the connection for this source

full_name

string
Required

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

description

string
Required

Description of the connection

team_id

string
Required

ID of the project

destination

Destination
Required

Associated Destination object

source

Source
Required

Associated Source object

rules

Rule[]
Required

Array of rules configured on the connection

disabled_at

string
Required
Date

Date the connection was disabled

paused_at

string
Required
Date

Date the connection was paused

updated_at

string
Required
Date

Date the connection was last updated

created_at

string
Required
Date

Date the connection was created

Retrieve all connections

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