Change history events hook capability

Overview

This topic explains how to use the change history events hook integration framework capability.

About the change history events hook

A change history events hook is a webhook 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.

The auditLogEventsHook has four properties:

• endpoint: The HTTP handler that will receive the webhook.
• templates: A map of template paths relative to your integration's directory. You can use templates to transform the raw change history events to a format that your integration expects. These templates can be any file type.
• defaultPolicy: An array of LaunchDarkly policies. The policies determine which events to send to your webhook endpoint. To learn more, read Using policies.
• includeErrorResponseBody (optional): Lets you to view any errors LaunchDarkly receives when it sends events to your endpoint.

Here's an example of a change history events hook capability that subscribes to flag events in a LaunchDarkly account:

The endpoint property

Every auditLogEventsHook capability must specify the endpoint LaunchDarkly should send webhook data to. To learn more, read Endpoints.

The templates property

Before the auditLogEventsHook capability sends the request to the endpoint handling your webhook, you can transform the body of the request it sends to your handler.

In your manifest, you can specify templates to execute when webhook events are of kinds flag, project, and environment. Additionally, you can specify a default template as a catch-all for any event without a more specific template. You can also specify a validation template to provide members with the ability to validate their connection by sending a test event from LaunchDarkly to your service.

Here is an example:

If you don't provide one or more templates, LaunchDarkly sends you a default JSON payload that looks like this:

If you choose to provide one or more templates, LaunchDarkly renders your template using the context data above. Your template can be any text-based format, but you must specify the appropriate Content-Type header in your endpoint.headers property to match the content type of your template body.

LaunchDarkly uses a basic subset of the Handlebars template syntax to render your template. To learn more about Handlebars syntax, read the Handlebars Language Guide.

In addition to the basic language syntax, LaunchDarkly supports the following built-in helpers:

• if
• unless
• each
• with
• lookup

To learn more, read Built-in Helpers.

LaunchDarkly also supports the following custom helpers:

• equal: renders a block if the string version of both arguments are equal
• pathEncode: URL path encodes the string version of the argument
• queryEncode: URL query encodes the string version of the argument
• basicAuthHeaderValue: transforms username and password arguments into the Authorization header value required for a basic auth, including the Basic prefix
• formatWithOffset: adds an offset in seconds to a Unix milliseconds timestamp and formats the timestamp using one of the supported formats detailed below

LaunchDarkly supports the following timestamp formats:

• milliseconds: Unix milliseconds
• seconds: Unix seconds
• rfc3339: RFC3339 format, for example, 2020-02-04T01:02:14Z
• simple: timestamp string formatted as yyyy-mm-dd h:MM:ss, for example, 2020-02-04 01:03:59

To test your templates, you can run npm run preview $INTEGRATION_NAME or use the Handlebars Sandbox.

The default policy property

People who use your integration can specify an array of LaunchDarkly policies to filter which events to send to your webhook endpoint. To learn more, read Using policies

To simplify onboarding your integration, you can specify a default policy which follows best practices for your integration's use case.

Assuming your integration only cares about flag activity, we recommend the following default policy. This policy specifies that LaunchDarkly will notify your integration of all flag activity across production environments from all projects.

Here is the policy:

The include error response body property

A static domain is one in which the domain part of the endpoint is not a template variable. For endpoints defined with static domains, you can specify the optional property includeErrorResponseBody in your auditLogEventsHook configuration to view any errors LaunchDarkly receives when it sends events to your endpoint. This is particularly useful for members troubleshooting issues with their integration.

Here is an example:

Previewing your webhook

To preview your integration's templates with sample data, run npm run preview $INTEGRATION_NAME.

Alternatively, to produce a sample curl command, run npm run curl $INTEGRATION_NAME. This returns data with your integration's service as if it was sent by the change history event hook capability.