Building a change history event hook integration

Overview

This guide explains how LaunchDarkly partners can use the integration framework to build a change history event hook integration. By the end of this guide, you as a LaunchDarkly partner should have the information you need to create a change history events hook integration that LaunchDarkly sends whenever an event happens inside of LaunchDarkly.

Each of these events results in an event being published to LaunchDarkly's change history. You can use this capability to send data to or trigger an event in another service.

Change history events

Every resource you change in LaunchDarkly generates an associated change history entry. Your integration can transform these events into a format that a POST endpoint can receive. Your team can configure the POST endpoint when they set up the integration.

A common use case for the events hook is associating feature flag changes with targeting changes in a specific environment. However, integrations are not limited to that resource only. For a full list of supported resources, read About resource types and scopes.

Build an integration

To build an integration, make sure you meet the prerequisites. Then follow the steps outlined on the Getting started page.

The Getting started page explains each of the following steps in detail:

1. Forking the LaunchDarkly Integration Framework repository.
2. Creating a new directory.
3. Creating an integration manifest.

• For an example of a completed manifest, read the Manifest.json example.

4. Collecting integration configuration data.
5. Defining the integration's capabilities.

• For this integration, define an auditLogEventsHook integration.
• To review the fields for the source payload, read Sample Context which contains a directory of samples with pre-transformed contexts.

6. Validating the integration.
7. Creating end-user documentation and README.
8. Submitting the integration.

The following sections provide configuration guidance specific to change history events hook integrations.

Authentication

A change history event hook integration can use either API keys or OAuth for authentication:

• Most integrations use API Keys. If you use API keys, configure them as outlined in the Collecting integration configuration data step on the Getting started page.
• If you use OAuth, configure it in the root of the manifest. To learn more, read Defining an integration manifest and Registering a LaunchDarkly OAuth client.

For an example OAuth integration, read AppDynamics Manifest under requiresOAuth. Integrations with require OAuth can still request additional formVariables.

The example below uses API Keys.

Manifest.json example

This example is looking for a flag template file under templates/flag.json.

The defaultPolicy limits the events to flag targeting changes for targeting in all production environments of all projects:

{
	"name": "Sample Integration",
	"version": "1.0.0",
	"overview": "Short one-liner describing your integration.",
	"description": "Send flag data to space. Markdown-based description.",
	"author": "Example Dot Com",
	"supportEmail": "support@example.com",
	"links": {
		"site": "https://example.com",
		"privacyPolicy": "https://example.com/privacy"
	},
	"categories": ["monitoring"],
	"icons": {
		"square": "assets/images/square.svg",
		"horizontal": "assets/images/horizontal.svg"
	},
	"requiresOAuth": false,
	"formVariables": [{
			"key": "apiToken",
			"name": "API key",
			"type": "string",
			"description": "Enter your Example [API key](https://example.com).",
			"isSecret": true
		},
		{
			"key": "endpointUrl",
			"name": "Example host URL",
			"description": "Your Example host URL.",
			"type": "enum",
			"allowedValues": [
				"https://api.example.com",
				"https://api.example.eu"
			],
			"isOptional": true,
			"defaultValue": "https://api.example.com"
		}
	],
	"capabilities": {
		"auditLogEventsHook": {
			"includeErrorResponseBody": false,
			"endpoint": {
				"url": "{{endpointUrl}}",
				"method": "POST",
				"headers": [{
						"name": "Content-Type",
						"value": "application/json"
					},
					{
						"name": "Authorization",
						"value": "Bearer {{apiToken}}"
					}
				]
			},
			"templates": {
				"flag": "templates/flag.json"
			},
			"defaultPolicy": [{
				"effect": "allow",
				"resources": ["proj/*:env/production:flag/*"],
				"actions": [
					"updateFlagVariations",
					"updateGlobalArchived"
					"updateOn",
					"updateRules"
					"updatePrerequisites",
					"updateTargets",
					"createFlag",
					"deleteFlag"
				]
			},
			{
				"effect": "allow",
				"resources": ["proj/*:env/production:segment/*"],
				"actions": [
					"createSegment",
					"deleteSegment"
					"updateExcluded",
					"updateIncluded"
					"updateRules"
				]
			},
			]
		}
	}
}
COPY

Default flag template file

You can customize the flag template file as needed to control the rendering of your JSON payload to fit your expected output. If you don't customize the template, then the webhook uses the default template.

Here is the default template:

{
  "date": "{{timestamp.rfc3339}}",
  "event": {
    "kind": "{{kind}}",
    "action": "{{verbKind}}"
  },
  "tags": "{{tags}}",
  "message": "{{{title.plainText}}}",
  "details": "{{{details.plainText}}}",
  "comment": "{{#if comment}}{{{comment}}}{{/if}}"
}
COPY

Conclusion

This guide describes the process of building a change history event hook integration. To learn more about building your own integrations, read Building partner integrations.