Webhooks¶

Blink can send webhooks when file changes occur, allowing integration with other systems. This is useful for triggering builds, running tests, sending notifications, or any other action you want to perform when files change.

Basic Usage¶

To send webhooks, use the --webhook-url flag:

blink --webhook-url "https://example.com/webhook"

This will send a POST request to the specified URL whenever a file changes.

Webhook Payload¶

The webhook payload is a JSON object with the following fields:

{
  "path": "/path/to/changed/file.js",
  "event_type": "write",
  "time": "2023-03-08T12:34:56.789Z"
}

path: The path of the file that changed
event_type: The type of event (create, write, remove, rename, chmod)
time: The time the event occurred (ISO 8601 format)

Customizing Webhooks¶

HTTP Method¶

By default, webhooks are sent using the POST method. You can specify a different method using the --webhook-method flag:

blink --webhook-url "https://example.com/webhook" --webhook-method "PUT"

Headers¶

You can add custom headers to webhook requests using the --webhook-headers flag:

blink --webhook-url "https://example.com/webhook" --webhook-headers "Authorization:Bearer token,Content-Type:application/json"

Headers are specified as a comma-separated list of key-value pairs, where each pair is separated by a colon.

Timeout¶

You can set a timeout for webhook requests using the --webhook-timeout flag:

blink --webhook-url "https://example.com/webhook" --webhook-timeout 10s

The timeout is specified as a duration (e.g., 5s, 1m, 500ms).

Retries¶

By default, Blink will retry failed webhook requests up to 3 times. You can change this using the --webhook-max-retries flag:

blink --webhook-url "https://example.com/webhook" --webhook-max-retries 5

Debouncing¶

To reduce the number of webhook requests, you can debounce them using the --webhook-debounce-duration flag:

blink --webhook-url "https://example.com/webhook" --webhook-debounce-duration 500ms

This will ensure that only one webhook is sent for each file within the specified duration, even if multiple events occur.

Filtering Webhooks¶

You can combine webhooks with event filtering to only send webhooks for specific files or event types:

# Only send webhooks for changes to JavaScript files
blink --webhook-url "https://example.com/webhook" --include "*.js"

# Only send webhooks for write events
blink --webhook-url "https://example.com/webhook" --events "write"

# Complex webhook filtering
blink --webhook-url "https://example.com/webhook" --include "*.js" --events "write"

Using Webhooks in the Go Library¶

If you're using Blink as a library in your Go projects, you can use the webhook API:

import (
    "time"
    "github.com/TFMV/blink/pkg/blink"
)

func main() {
    // Start the event server with webhooks
    blink.EventServer(
        ".",                  // Directory to watch
        "*",                  // Allow all origins
        ":12345",             // Listen on port 12345
        "/events",            // Event path
        100*time.Millisecond, // Refresh duration
        // Webhook options
        blink.WithWebhook("https://example.com/webhook", "POST"),
        blink.WithWebhookHeaders(map[string]string{
            "Authorization": "Bearer token",
            "Content-Type": "application/json",
        }),
        blink.WithWebhookTimeout(10*time.Second),
        blink.WithWebhookDebounce(500*time.Millisecond),
        blink.WithWebhookRetries(5),
    )

    select {}
}

Example Use Cases¶

Triggering CI/CD Pipelines¶

You can use webhooks to trigger CI/CD pipelines when code changes:

blink --webhook-url "https://jenkins.example.com/job/my-project/build" --include "*.go" --events "write"

Sending Slack Notifications¶

You can send notifications to Slack when important files change:

blink --webhook-url "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" --include "config.yaml,*.env" --events "write"

Running Tests¶

You can run tests when test files change:

blink --webhook-url "http://localhost:8080/run-tests" --include "*_test.go" --events "write"

Reloading Web Servers¶

You can reload web servers when configuration files change:

blink --webhook-url "http://localhost:8080/reload" --include "nginx.conf,*.conf" --events "write"