# Getting started

Copy as Markdown[View as Markdown](/docs/plugins/hookdeck/intro.md)

***

[Hookdeck](https://hookdeck.com?ref=eventcatalog-docs) is an event gateway that provides serverless infrastructure, features, tooling to enable the full software development lifecycle of event-driven applications.

Using the EventCatalog Hookdeck plugin you can extract information from Hookdeck to gain further understanding of event sources, destinations, and flows within the Hookdeck platform.

### Core Features[​](#core-features "Direct link to Core Features")

The Hookdeck plugin can provide you with the following features:

* ⭐️ [Generate EventCatalog Services](#generate-services) from Hookdeck Sources and Destinations
* ⭐️ [Auto-generate EventCatalog Messages](#generate-messages) from Hookdeck Requests and Events
* ⭐️ [Auto-generate EventCatalog Message Schemas](#generate-schemas) from Hookdeck Requests and Events
* ⭐️ [Provide insight into Hookdeck Filters](#filtered-messages) by indicating Requests that are received by an EventCatalog Service but are not connected to destination Service.

### How it works[​](#how-it-works "Direct link to How it works")

EventCatalog supports [generators](/docs/plugins/generators.md). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk.md) to give developers easier access to their catalogs through custom scripts or generators.

The EventCatalog Hookdeck plugin queries the [Hookdeck API](https://hookdeck.com/docs/api?ref=eventcatalog-docs) to generate an EventCatalog visualization including Services and Messages. It also generates inferred Message schemas.

The plugin can either be used as a plugin within an EventCatalog instance or as a CLI configured to point to an EventCatalog instance.

### Getting started[​](#getting-started "Direct link to Getting started")

#### 1. Install the plugin[​](#1-install-the-plugin "Direct link to 1. Install the plugin")

```
npm i @hookdeck/eventcatalog-generator
```

#### 2. Configure your generator in your `eventcatalog.config.js` file[​](#2-configure-your-generator-in-your-eventcatalogconfigjs-file "Direct link to 2-configure-your-generator-in-your-eventcatalogconfigjs-file")

eventcatalog.config.js

```
/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
export default {
  title: 'OurLogix',
  tagline: 'A comprehensive logistics and shipping management company',
  organizationName: 'OurLogix',
  homepageLink: 'https://eventcatalog.dev/',
  landingPage: '',
  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
  trailingSlash: false,
  base: '/',
  logo: {
    alt: 'EventCatalog Logo',
    src: '/logo.png',
    text: 'OurLogix',
  },
  docs: {
    sidebar: {
      showPageHeadings: true,
    },
  },
  generators: [
    [
      "@hookdeck/eventcatalog-generator",
      {
        hookdeckApiKey: process.env.HOOKDECK_API_KEY,
        domain: "Payments",
        connectionSourcedMatch: "payments-.*",
        processMaxEvents: 200,
        logLevel: "debug",
      },
    ],
  ],
};
```

#### 3. Run the generate command[​](#3-run-the-generate-command "Direct link to 3. Run the generate command")

*This command will run the generators in your eventcatalog.config.js file.*

```
npm run generate
```

#### 4. View your catalog[​](#4-view-your-catalog "Direct link to 4. View your catalog")

Run your catalog locally to see the changes:

```
npm run dev
```

![Example](/assets/images/example-2cfee9fadccd630eea392329d04416bb.png)

## Hookdeck Concepts[​](#hookdeck-concepts "Direct link to Hookdeck Concepts")

### Sources[​](#sources "Direct link to Sources")

A Hookdeck [Source](https://hookdeck.com/docs/sources?ref=eventcatalog-docs) represents any service that makes an HTTP request to Hookdeck. The HTTP requests can be inbound events such as webhooks or asynchronous API calls.

### Destinations[​](#destinations "Direct link to Destinations")

A Hookdeck [Destination](https://hookdeck.com/docs/destinations?ref=eventcatalog-docs) represents the destination for an event to be routed to. A destination can be connected to one or many Sources.

### Connections[​](#connections "Direct link to Connections")

[Connections](https://hookdeck.com/docs/connection?ref=eventcatalog-docs) in Hookdeck route an event from a Source to a Destination. Connections can reuse sources and destinations, allowing one event to be routed to multiple destinations.

### Event lifecycle[​](#event-lifecycle "Direct link to Event lifecycle")

The following represent different stages of the lifecycle of an event within Hookdeck:

* [Requests](https://hookdeck.com/docs/requests?ref=eventcatalog-docs): An HTTP request received by a Source URL defined within Hookdeck, such as a webhook.
* [Events](https://hookdeck.com/docs/events?ref=eventcatalog-docs): An outbound event payload that Hookdeck has queued for delivery.
* [Attempts](https://hookdeck.com/docs/attempts?ref=eventcatalog-docs): An HTTP delivery attempt to the URL defined by a Destination.

## Features[​](#features "Direct link to Features")

### Generate EventCatalog Services[​](#generate-services "Direct link to Generate EventCatalog Services")

The Hookdeck plugin generates EventCatalog Services from Sources and Destinations that are used within defined Hookdeck Connections. The Sources and Destinations that have Services created can be filtered using the `connectionSourcedMatch` configuration option which performs a regular expression match on the connection source name.

### Auto-generate EventCatalog Messages[​](#generate-message "Direct link to Auto-generate EventCatalog Messages")

EventCatalog Messages are generated for Requests received by a Source and Events received by a Destination. The number of Hookdeck Request and Events to have EventCatalog Messages generated can be set using the `processMaxEvents` configuration option.

By default, the plugin search for a `type` or `eventType` property on the event payload to uniquely identify a Request or Event type. If the property cannot be found, each Request or Event is treated as a unique Message within EventCatalog.

### Auto-generate EventCatalog Message Schemas[​](#generate-schemas "Direct link to Auto-generate EventCatalog Message Schemas")

Hookdeck does not presently support schemas. Therefore, a Message schema can only be inferred from an event payload. The Hookdeck EventCatalog plugin generates inferred schemas for the first instance of an Event type and Request type it processes.

### Provide insight into Hookdeck Filters[​](#filtered-messages "Direct link to Provide insight into Hookdeck Filters")

Hookdeck supports the ability to [filter events](https://hookdeck.com/docs/filters?ref=eventcatalog-docs) based on header or body contents. This can result in Sources receiving Requests but not Events being generated. EventCatalog's visual representation help you identify where events are being entirely filtered out and not delivered to any destination service.

## Commercial Use[​](#commercial-use "Direct link to Commercial Use")

This plugin is free to use for commercial use.

## Source[​](#source "Direct link to Source")

<https://github.com/hookdeck/eventcatalog-generator>

## Issues[​](#issues "Direct link to Issues")

If you have any problems or feature requests please raise them on GitHub: <https://github.com/hookdeck/eventcatalog-generator/issues>