Succeeding with Hookdeck

Hookdeck aims to alleviate the many challenges that come with developing event-driven integrations. The following practices will help set you up for success with the platform.

Use the CLI to receive requests on your local server

When using solutions like ngrok, teams have to avoid flooding each other with unwanted webhooks. That's why we recommend using Hookdeck CLI to develop and test your webhook integrations locally.

With the CLI, each team member receives their own copy of a webhook, and the history is isolated per team member. Each team member can also listen to just the pertinent events, rather than all the webhooks received at a given URL. Events sent to the CLI are available on your dashboard and can be browsed, filtered, and replayed just like production events.

Use bookmarks for integration tests

Instead of keeping stale JSON checks in your repo, you can use your event history as mock data for future integration tests. Use bookmarks to store and replay representative payloads.

Replace your event queue

Implementing a event queue on your own server when receiving events from Hookdeck is redundant. That's because Hookdeck already behaves as a push queue, eliminating the need to implement a queue of your own. To control the rate at which your server processes requests, simply set a rate limit on your destination.

Handle events synchronously

It's common knowledge that you should not take action immediately upon receiving an asyn request (ie. webhook). But with Hookdeck, you can safely perform server-side operations as soon as you receive an event. It provides a 60-second timeout window for you to process each inbound event, and return a representative response and HTTP status code. Process webhooks synchronously to make the most of Hookdeck.

Handle events in order

With or without Hookdeck, there's no guarantee what order events will arrive in. That's why it's important that your destination server use its own logic to order events upon receiving them. Always use relevant data from the provider's payload, such as an updated_at value, to ensure you don't process stale requests that might overwrite more recent updates.

Implement idempotency

Most events & webhook providers, including Hookdeck, operate on an "at least once" approach. This means an event may be successfully delivered more than once. Because there is no guarantee that requests will be delivered only once, actions taken on an event by your destination server should be idempotent.

Integrate with CI & CD

Using the admin API, Hookdeck can be integrated within your CI & CD workflow. We recommend creating connections from the API before your endpoints are deployed to avoid a situation where you've forgotten to configure a connection.