Skip to content

HTTP_FORWARDING.md

Latest commit

 

History

History
133 lines (92 loc) · 3.29 KB

HTTP_FORWARDING.md

File metadata and controls

133 lines (92 loc) · 3.29 KB
Raw

HTTP Forwarding

SignalBox can forward accepted unique webhook events to an external HTTP endpoint through the durable delivery_jobs queue.

incoming webhook -> dedupe -> PostgreSQL event -> delivery_jobs -> HTTP POST -> retry/backoff

This makes SignalBox usable not only as a Telegram notification relay, but also as a classic webhook gateway.

Source settings

When creating or updating a source, configure:

{
  "name": "GitHub events",
  "forward_url": "https://example.com/webhooks/signalbox",
  "forward_hmac_key": "your-shared-key"
}

forward_url is optional. If it is not set, no HTTP forwarding job is created.

forward_hmac_key is optional. If it is set, SignalBox signs outgoing HTTP forwarding requests.

The key is not returned by the API. Responses only expose whether it is configured:

{
  "forward_hmac_key_set": true
}

Forward URL safety

HTTP forwarding is designed for external webhook targets. To reduce SSRF risk, SignalBox blocks forwarding to local and private network destinations by default.

Rejected destinations include:

localhost
*.localhost
*.local
127.0.0.0/8
10.0.0.0/8
172.16.0.0/12
192.168.0.0/16
loopback, link-local, multicast and unspecified IPv6 targets

SignalBox validates both literal IP hosts and DNS resolution results before sending an HTTP forwarding request. Unsafe targets are marked as failed delivery jobs instead of being called.

For private self-hosted topologies, prefer routing through an explicit public/internal gateway. A future allowlist-based configuration can be added without weakening the hosted/default security model.

Delivery behavior

HTTP forwarding uses the same durable delivery queue as Telegram delivery.

  • each unique event creates an http delivery job when forward_url is configured;
  • duplicate events are stored but do not enqueue a new forwarding job;
  • failed requests are retried with exponential backoff;
  • Retry-After is respected when the target endpoint returns it;
  • jobs become terminal failed after DELIVERY_MAX_ATTEMPTS.

Outgoing request

SignalBox sends the original JSON payload to the target endpoint.

Additional headers:

X-SignalBox-Event-ID
X-SignalBox-Delivery-ID
X-SignalBox-Source-ID
X-SignalBox-Event-Type
X-SignalBox-Timestamp
X-SignalBox-Signature

X-SignalBox-Signature is included only when forward_hmac_key is configured.

Signature format

SignalBox signs:

<timestamp>.<raw_json_body>

The signature uses HMAC-SHA256 and is sent as:

X-SignalBox-Signature: sha256=<hex_digest>

Recommended receiver checks:

  • verify the signature;
  • reject old timestamps, for example older than 5 minutes;
  • make receiver idempotent using X-SignalBox-Event-ID;
  • return 2xx only after successful processing;
  • return 429 with Retry-After when overloaded.

Admin UI

The embedded Admin UI supports creating a source with:

  • Telegram chat id;
  • HTTP forward URL;
  • HTTP forward HMAC key.

Open:

/admin

Delivery inspection

List HTTP delivery jobs:

curl "https://signalbox.example.com/v1/deliveries?channel=http" \
  -H "X-API-Key: <ADMIN_API_KEY>"

Retry one failed HTTP delivery:

curl -X POST https://signalbox.example.com/v1/deliveries/<DELIVERY_ID>/retry \
  -H "X-API-Key: <ADMIN_API_KEY>"