Stream Network Activity to a Generic HTTP Endpoint

The Generic HTTP integration allows you to stream your NetBird network activity events to any custom HTTP/S endpoint. This provides a flexible way to connect NetBird with a wide range of third-party systems, including custom SIEMs, log management tools like Grafana Loki, or any service that can receive POST requests.

For every event, NetBird will send a POST request to your configured endpoint. You have full control over the request's body format and headers, allowing for seamless integration with various APIs.

Prerequisites

Before you start, ensure you have an HTTP/S endpoint that is publicly accessible and ready to receive POST requests from NetBird. You will also need any necessary authentication details, such as an API key or credentials for Basic Authentication.

Create an Integration in NetBird

1. Navigate to the Integrations tab in the NetBird dashboard and select Event Streaming.
2. Find the Generic HTTP option and click Connect.
3. A configuration panel will open with several tabs: General, Headers, Body Template, and Danger Zone.

General Configuration

This tab is for the essential endpoint details.

• Endpoint URL: Enter the full HTTPS or HTTP URL where NetBird should send the events. This field is mandatory.
• Authentication: Select the authentication method required by your endpoint.
  • No Authentication: Sends requests without an Authorization header.
  • Bearer Token: Adds an Authorization: Bearer <your-token> header to each request. You will need to provide your API key or token.
  • Basic Auth: Adds an Authorization: Basic <credentials> header. You must provide the credentials in the format username:password.

HTTP Headers (Optional)

You can add custom HTTP headers to every outgoing request in the Headers tab. This is useful for passing static tokens, setting a custom Content-Type, or other API requirements. By default, the Content-Type is application/json.

Custom Body Template (Optional)

The Body Template tab gives you powerful control over the structure of the JSON payload sent to your endpoint.

If this option is disabled, NetBird sends a default JSON object for each event. When enabled, you can define your own payload structure using Go's text/template templating engine.

This is especially useful for integrating with services that expect a specific format, like Grafana Loki.

Available Template Variables

You can use the following variables from the StreamEvent object in your template:

Danger Zone

This tab allows you to delete the integration. This action is irreversible and will immediately stop events from being sent to your endpoint.

After configuring all settings, click Save Changes.

Verify the Integration

Once you save the integration, NetBird sends a test event to your endpoint to confirm that the connection and authentication are successful.

Check the logs of your receiving service for a new POST request. You should find a JSON payload similar to this (if custom template wasn't set up):

{
    "ID": "test-event-1685635200",
    "Timestamp": "2025-06-01T16:00:00Z",
    "Message": "integration test event for generic http endpoint",
    "InitiatorID": "netbird-test-system",
    "TargetID": "target-id",
    "Meta": {
        "purpose": "configuration-test",
        "source": "netbird-test"
    },
    "Reference": "netbird:test:generichttp"
}