webhooks/

directory
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT

README

OwlMail webhook examples

These examples are intentionally separate: start with the smallest file that matches your use case instead of deleting fields from one large configuration.

Scenario Configuration What it demonstrates
Send every new email minimal.json The two required target fields and OwlMail's default JSON event.
Route selected alerts filtered-alerts.json Recipient and subject matching, timeout, and retries.
Call an authenticated JSON API custom-json.json Environment-backed URL/token/secret, custom headers, HMAC, and a JSON-safe template.
Fan out to several destinations multiple-targets.json An archive target plus a filtered incident target. One email may match both.
Send a plain-text message plain-text.json A non-JSON content type and a text template.
Integrate with soulteary/webhook soulteary-webhook/ A complete Docker Compose stack, HMAC validation, payload mapping, and command execution.
Full single-file reference ../webhooks.json Most target options together in one configuration.

Five-minute local smoke test

The bundled receiver listens only on 127.0.0.1:18080, prints each request, returns HTTP 204, and can optionally verify OwlMail's HMAC signature.

Terminal 1 — start the receiver:

go run ./examples/webhooks/receiver

Terminal 2 — start OwlMail with the minimal configuration:

go run ./cmd/owlmail -webhook-config ./examples/webhooks/minimal.json

Terminal 3 — send a test email (curl must include SMTP protocol support):

printf 'From: sender@example.test\r\nTo: inbox@example.test\r\nSubject: Minimal webhook\r\n\r\nHello from OwlMail.\r\n' \
  | curl --url smtp://127.0.0.1:1025 \
      --mail-from sender@example.test \
      --mail-rcpt inbox@example.test \
      --upload-file -

The receiver output includes the request path, event type, email ID, content type, signature state, and body. Stop both processes with Ctrl+C.

Run each scenario

Minimal: forward everything
./owlmail -webhook-config ./examples/webhooks/minimal.json

There is no match, bodyTemplate, secret, or custom header, so every new email is sent once using OwlMail's default email.received JSON payload.

Filter alerts
./owlmail -webhook-config ./examples/webhooks/filtered-alerts.json

An email must match at least one to pattern and at least one subject pattern. Change the example addresses and words to match your own alerts.

Authenticated custom JSON

Start the example receiver with signature verification:

export OWLMAIL_WEBHOOK_SECRET='replace-this-development-secret'
go run ./examples/webhooks/receiver

In the OwlMail terminal, set every placeholder used by the configuration:

export OWLMAIL_WEBHOOK_URL='http://127.0.0.1:18080/custom'
export OWLMAIL_WEBHOOK_TOKEN='development-token'
export OWLMAIL_WEBHOOK_SECRET='replace-this-development-secret'
./owlmail -webhook-config ./examples/webhooks/custom-json.json

The receiver verifies X-OwlMail-Signature-V2, enforces a five-minute signing window, and rejects reused nonces. It deliberately logs only whether the Authorization header is present, never its value.

Multiple targets
./owlmail -webhook-config ./examples/webhooks/multiple-targets.json

Every message goes to /archive. Messages addressed to ops@* whose subject contains critical or outage also go to /incidents. Destinations are evaluated in file order for each email.

Plain text
./owlmail -webhook-config ./examples/webhooks/plain-text.json

This sends text/plain; charset=utf-8 instead of JSON and truncates the message body to 2,000 Unicode characters.

Running OwlMail in a container

127.0.0.1 inside a container refers to that container. Replace the example URL with a Compose service name such as http://receiver:18080/owlmail, or with an address reachable from the OwlMail container. The soulteary-webhook example shows service-name routing.

Validate before deployment

OwlMail validates and compiles the complete file at startup. A missing or empty environment variable, unknown JSON field, bad duration, invalid wildcard, or invalid template prevents the service from starting. After changing a file, restart OwlMail; webhook configuration is not hot-reloaded.

OwlMail runs at most eight email webhook jobs concurrently by default. Keep the recommended limit for most development and CI workloads; use -webhook-max-concurrency 0 only for deliberately unlimited concurrency.

See the full English reference or 中文参考 for every field, payload, header, matching rule, retry behavior, and security boundary.

Directories

Path Synopsis
Command receiver runs a loopback-only HTTP endpoint for exercising OwlMail webhook configurations during local development.
Command receiver runs a loopback-only HTTP endpoint for exercising OwlMail webhook configurations during local development.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL