tiny-forge/docs/webhooks.md

Outgoing webhooks

Tinyforge posts JSON events to a configured URL when deploys and static-site syncs finish. Receivers can verify each request was sent by Tinyforge and not tampered with by checking the HMAC-SHA256 signature on the body.

Tiers and resolution

A single global URL is rarely enough — different teams own different projects, and operators often want to route prod failures somewhere noisier than dev failures. Tinyforge supports four tiers:

Tier	Where set	Used for
stage	Stage edit form	Per-stage deploys
project	Project edit form	All stages of a project
site	Static-site detail page	Static-site sync events
settings	Settings → Integrations	Global fallback

Resolution order:

• Deploys: stage → project → settings
• Sites: site → settings

The most-specific tier with a non-empty URL wins. The signing secret travels with the URL that sourced it: a stage can sign even when the project and global URLs are unsigned.

Signature scheme

Every request includes:

POST /your/handler HTTP/1.1
Content-Type: application/json
User-Agent: Tinyforge-Webhook/1
X-Hub-Signature-256: sha256=<hex>
X-Tinyforge-Event: deploy_success
X-Tinyforge-Delivery: 0f3a…-uuid
X-Tinyforge-Timestamp: 2026-05-07T12:34:56Z
X-Tinyforge-Tier: stage

The signature is HMAC-SHA256(secret, raw_body), hex-encoded, with the sha256= prefix — the GitHub X-Hub-Signature-256 format. Receivers already built for GitHub-style webhooks (Gitea, Forgejo, n8n, Hookdeck, the service-to-notification-bridge generic webhook provider) verify it without modification.

When no signing secret is configured for the resolved tier, the signature header is omitted and the request goes out unsigned. This is intentional back-compat for receivers that don't speak HMAC.

Receiver requirements

A correct verifier:

1. Reads the raw body bytes before any JSON parse / re-serialise.
2. Computes HMAC-SHA256(secret, body) and compares to the value after sha256= in X-Hub-Signature-256.
3. Uses a constant-time comparator (hmac.compare_digest / crypto.timingSafeEqual / hmac.Equal).
4. Returns 401/403 on mismatch — Tinyforge surfaces the receiver's status code in the UI when the operator clicks Send test.

Node / TypeScript

import { createHmac, timingSafeEqual } from 'crypto';

export function verify(secret: string, rawBody: Buffer, header: string): boolean {
  const got = header.startsWith('sha256=') ? header.slice(7) : header;
  const want = createHmac('sha256', secret).update(rawBody).digest('hex');
  if (got.length !== want.length) return false;
  return timingSafeEqual(Buffer.from(got, 'hex'), Buffer.from(want, 'hex'));
}

Python

import hmac
import hashlib

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    got = header[7:] if header.startswith("sha256=") else header
    want = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(got, want)

Go

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strings"
)

func verify(secret string, body []byte, header string) bool {
    got := strings.TrimPrefix(header, "sha256=")
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    want := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(got), []byte(want))
}

Event payload

{
  "type": "deploy_success",
  "project": "demo-app",
  "stage": "prod",
  "image_tag": "v1.4.2",
  "subdomain": "stage-prod-demo-app",
  "url": "https://stage-prod-demo-app.example.com",
  "timestamp": "2026-05-07T12:34:56Z"
}

type values:

• deploy_success, deploy_failure — sent by the deployer.
• site_sync_success, site_sync_failure — sent by the static-site manager. Use the project field as the site name; stage and image_tag are empty.
• test — sent by the Send test button. Treat it as a no-op or surface it in your operator log; never as a real deploy event.

Configuring the service-to-notification-bridge

If you're sending Tinyforge events to the service-to-notification-bridge generic webhook provider:

1. Create a Generic Webhook provider.
2. Set auth_mode = hmac_sha256.
3. Paste the same secret Tinyforge generated (revealed via the Outgoing webhook panel).
4. Set event_type_path = type so deploys and site syncs map to distinct event types in the bridge.
5. Add payload_mappings for project, stage, image_tag, url, error and reference them as {{ extra.project }} in your notification templates.

The bridge accepts X-Hub-Signature-256 natively (no header rename needed) and reads the raw body before parsing, so step 1 of the receiver requirements is already met.

Rotating secrets

Click Regenerate in the Outgoing webhook panel to rotate. The old secret is invalidated immediately — update receivers in lock-step or expect a brief window of 401s. There is no soft rollover today.

To send unsigned events to a legacy receiver that can't verify, click Disable signing. Tinyforge will keep dispatching events without the X-Hub-Signature-256 header until you regenerate.