Skip to content

README.md

Latest commit

 

History

History
244 lines (175 loc) · 6.54 KB

README.md

File metadata and controls

244 lines (175 loc) · 6.54 KB

CertWatch Webhook CLI

Deliver real Certificate Transparency webhook payloads to your local endpoint for testing.

Works with CertWatch's free webhook tester — generate a secret on the web page, then run the CLI to stream live CT certificate data as formatted webhook payloads to your endpoint.

Quick Start

Preview (no setup needed)

npx certwatch-webhook-cli --preview

Deliver to your endpoint

npx certwatch-webhook-cli --secret <secret> --url http://localhost:3000/webhook

Go (pre-built binary)

# macOS / Linux (Homebrew)
brew install certwatch-app/tap/certwatch-webhook-cli

# Linux (without Homebrew)
curl -sL https://github.com/certwatch-app/certwatch-webhook-cli/releases/latest/download/certwatch-webhook-cli_linux_amd64.tar.gz | sudo tar xz -C /usr/local/bin
# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/certwatch-app/certwatch-webhook-cli/releases/latest/download/certwatch-webhook-cli_windows_amd64.zip -OutFile certwatch-webhook-cli.zip
Expand-Archive certwatch-webhook-cli.zip -DestinationPath .
# Then run
certwatch-webhook-cli -secret <secret> -url http://localhost:3000/webhook

Usage

Preview mode (instant, offline)

See exactly what a webhook delivery looks like — no secret or session required:

# Node.js
npx certwatch-webhook-cli --preview

# Preview with your real secret to test HMAC verification
npx certwatch-webhook-cli --preview --secret abc123...

# Go
certwatch-webhook-cli -preview
certwatch-webhook-cli -preview -secret abc123...

Deliver to your endpoint

  1. Visit certwatch.app/tools/webhook-tester
  2. Click "Generate Secret" to get a test secret
  3. Run the CLI:
# Node.js
npx certwatch-webhook-cli --secret abc123... --url http://localhost:3000/webhook

# Go
certwatch-webhook-cli -secret abc123... -url http://localhost:3000/webhook

Save payloads to a file

Save received payloads as JSONL for test fixtures or replay:

npx certwatch-webhook-cli --secret abc123... --file payloads.jsonl

Pipe raw JSON to another tool

Output NDJSON to stdout (suppresses all decorative output):

npx certwatch-webhook-cli --secret abc123... --raw | jq '.data.common_name'

Combine output modes

Output modes are combinable — deliver, save, and pipe simultaneously:

npx certwatch-webhook-cli --secret abc123... \
  --url http://localhost:3000/webhook \
  --file payloads.jsonl

API key mode (auto-creates session)

If you have a CertWatch account, use your API key for higher limits:

# Node.js
npx certwatch-webhook-cli --api-key cw_xxx_yyy --url http://localhost:3000/webhook

# Go
certwatch-webhook-cli -api-key cw_xxx_yyy -url http://localhost:3000/webhook

Options

Output modes (at least one required, combinable)

Flag Description
--url / -url Deliver payloads via HTTP POST to this URL
--file / -file Save payloads to a JSONL file (one JSON per line)
--raw / -raw Print raw NDJSON to stdout (pipe-friendly)
--preview / -preview Show a sample payload and exit (no session needed)

Authentication (required for --url, --file, --raw)

Flag Description
--secret / -secret Test secret from web page (anonymous mode)
--api-key / -api-key CertWatch API key (auto-creates session)

Other options

Flag Description Default
--verbose / -verbose Print full JSON payload per delivery false
--no-color / -no-color Disable ANSI colors (also: NO_COLOR env) false
--api-endpoint / -api-endpoint Override API base URL https://api.certwatch.app
--version / -version Print version

Rate Limits

Tier Sessions/hour Stream duration
Anonymous (no account) 1 60 seconds
Signed-up (any account) 5 90 seconds

Webhook Payload Format

Each delivery POSTs a JSON payload matching CertWatch's production webhook format:

{
  "event": "ct.certificate.new",
  "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-07T12:00:00.000Z",
  "api_version": "2024-01-01",
  "data": {
    "fingerprint": "sha256:abc123...",
    "serial_number": "01:AB:CD:...",
    "common_name": "*.example.com",
    "domains": ["*.example.com", "example.com"],
    "issuer_org": "Let's Encrypt",
    "issuer_cn": "R3",
    "not_before": "2026-02-07T00:00:00.000Z",
    "not_after": "2026-05-08T00:00:00.000Z",
    "ct_log_sources": ["Google Argon 2026"],
    "seen_at": "2026-02-07T12:00:00.000Z"
  }
}

Headers

Header Description
Content-Type application/json
User-Agent CertWatch-Webhook/1.0
X-CertWatch-Event-Id Unique event ID
X-CertWatch-Timestamp ISO 8601 timestamp
X-CertWatch-Signature sha256={hmac_hex}

Verifying Signatures

The X-CertWatch-Signature header contains an HMAC-SHA256 signature of the raw JSON body, signed with your test secret. Verify it in your endpoint:

const crypto = require('crypto');

function verifySignature(body, secret, signatureHeader) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return signatureHeader === `sha256=${expected}`;
}

Example Receiver Server

Don't have a webhook endpoint yet? Use our example receiver to get started. It listens for payloads, verifies HMAC signatures, and pretty-prints the results.

# Terminal 1 — start the receiver (Node.js)
node examples/receiver.js --secret <secret> --port 3000

# Terminal 1 — start the receiver (Go)
go run examples/receiver.go -secret <secret> -port 3000

# Terminal 2 — send payloads via CLI
npx certwatch-webhook-cli --secret <secret> --url http://localhost:3000/webhook

Output:

  CertWatch Webhook Receiver

  Listening: http://localhost:3000/webhook
  Health:    http://localhost:3000/health
  Secret:    abc12345...

  Waiting for payloads...

  #1  *.example.com
      Domains: 2  Issuer: R11
      Event:   evt_550e8400-e29b-41d4-a716-446655440000
      HMAC:    VERIFIED
      2026-02-07T14:00:00Z

The examples are standalone files with zero dependencies — use them as a starting point for your own webhook handler.

Development

# Node.js
cd node && npm install && npm run typecheck && npm run build

# Go
cd go && make build && make test

License

MIT