`@backstage/plugin-events-backend`

Welcome to the events-backend backend plugin!

This package is based on events-node and its eventsServiceRef that is at the core of the event support. It provides an eventsPlugin (exported as default).

By default, the plugin ships with support to receive events via HTTP endpoints POST /api/events/http/{topic} and will publish these to the EventsService.

HTTP ingresses can be enabled by config, or using the extension point of the eventsPlugin. Additionally, the latter allows to add a request validator (e.g., signature verification).

Installation

bash

# From your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-events-backend

// packages/backend/src/index.ts
backend.add(import('@backstage/plugin-events-backend'));

Configuration

In order to create HTTP endpoints to receive events for a certain topic, you need to add them at your configuration:

yaml

events:
  http:
    topics:
      - bitbucketCloud
      - github
      - whatever

Only those topics added to the configuration will result in available endpoints.

The example above would result in the following endpoints:

POST /api/events/http/bitbucketCloud
POST /api/events/http/github
POST /api/events/http/whatever

You may want to use these for webhooks by SCM providers in combination with suitable event subscribers.

However, it is not limited to these use cases.

Use Cases

Request Validator

import { eventsExtensionPoint } from '@backstage/plugin-events-node/alpha';

// [...]

export const eventsModuleYourFeature = createBackendModule({
  pluginId: 'events',
  moduleId: 'your-feature',
  register(env) {
    // [...]
    env.registerInit({
      deps: {
        // [...]
        events: eventsExtensionPoint,
        // [...]
      },
      async init({ /* ... */ events /*, ... */ }) {
        // [...]
        events.addHttpPostIngress({
          topic: 'your-topic',
          validator: yourValidator,
        });
      },
    });
  },
});

Request Body Parse

We need to parse the request body before we can validate it. We have some default parsers but you can provide your own when necessary.

import { eventsExtensionPoint } from '@backstage/plugin-events-node/alpha';

// [...]

export const eventsModuleYourFeature = createBackendModule({
  pluginId: 'events',
  moduleId: 'your-feature',
  register(env) {
    // [...]
    env.registerInit({
      deps: {
        // [...]
        events: eventsExtensionPoint,
        // [...]
      },
      async init({ /* ... */ events /*, ... */ }) {
        // [...]
        events.addHttpPostBodyParser({
          contentType: 'application/x-www-form-urlencoded',
          parser: async (req, _topic) => {
            return {
              bodyParsed: req.body.toString('utf-8'),
              bodyBuffer: req.body,
              encoding: 'utf-8',
            };
          },
        });
      },
    });
  },
});

We have the following default parsers:

application/json