Documentation

API Base URL: https://hookpipe.app

Quick Start

1. Create an API Key

API keys authenticate you for hook management. The key is shown once at creation — save it.

curl -X POST https://hookpipe.app/api/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-key"}'

2. Create a Hook

A hook defines a receive endpoint, optional transform rules, and an optional destination URL. Leave out destinationUrl for a store-only hook: payloads are kept and you read them back through the payloads API, including by long-polling.

curl -X POST https://hookpipe.app/api/hooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-events",
    "destinationUrl": "https://your-app.com/webhook",
    "transformConfig": {
      "fieldMapping": {
        "repo": "repository.name",
        "actor": "sender.login"
      }
    }
  }'

The response includes an id — that's your hook ID for the receive URL.

3. Point Your Webhooks Here

Use https://hookpipe.app/hooks/YOUR_HOOK_ID as the webhook URL in whatever service you're integrating.

# Example: test it manually
curl -X POST https://hookpipe.app/hooks/YOUR_HOOK_ID \
  -H "Content-Type: application/json" \
  -d '{"repository": {"name": "my-repo"}, "sender": {"login": "dev"}}'

Guides

Detailed walkthroughs for specific use-cases. View all guides →

Transform Rules

Transform rules are optional. If you don't set transformConfig, the payload is forwarded as-is.

Field Mapping

Extract nested fields into a flat structure using dot notation:

"fieldMapping": {
  "repo": "repository.name",      // payload.repository.name → result.repo
  "actor": "sender.login",        // payload.sender.login → result.actor
  "action": "action"              // payload.action → result.action (top-level)
}

Filtering

Only forward payloads that match conditions. If a filter doesn't match, the payload is dropped (HTTP 200 returned to sender, nothing forwarded).

"filters": [
  {"field": "action", "operator": "equals", "value": "opened"},
  {"field": "repository.name", "operator": "contains", "value": "prod"}
]

Supported operators: equals, notEquals, contains, notContains, exists, notExists, greaterThan, lessThan.

Field Renaming

"renames": {
  "old_field_name": "new_field_name"
}

Adding Static Values

Add constant values by including them directly in fieldMapping. Use a non-dot-notation key with a literal string:

"fieldMapping": {
  "repo": "repository.name",
  "source": "github",
  "version": "1.0"
}

API Reference

Authentication

All /api/* endpoints require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The webhook receive endpoint (POST /hooks/:hookId) is public — no auth required.

# Seed the cursor with the newest payload ID (empty string = start from the oldest)
AFTER=$(curl -s https://hookpipe.app/api/hooks/YOUR_HOOK_ID/payloads?limit=1 \
  -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.data[0].id // ""')

# Each request returns as soon as a newer payload is stored, or after 30s with an empty list
while true; do
  RESP=$(curl -s "https://hookpipe.app/api/hooks/YOUR_HOOK_ID/payloads?after=$AFTER&wait=30" \
    -H "Authorization: Bearer YOUR_API_KEY")
  echo "$RESP" | jq -c '.data[]'            # handle each new payload here
  NEXT=$(echo "$RESP" | jq -r '.data[-1].id // empty')
  [ -n "$NEXT" ] && AFTER=$NEXT
done

Signature Validation

Verify that incoming webhooks are authentic by checking their HMAC signatures. Supports GitHub, Stripe, and generic HMAC providers.

Configure Signature Validation

curl -X PATCH https://hookpipe.app/api/hooks/HOOK_ID/signature \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "provider": "github",
    "secrets": ["your-webhook-secret"],
    "debug": true
  }'

Supported providers:

• github — verifies X-Hub-Signature-256 (SHA-256) with fallback to X-Hub-Signature (SHA-1)
• stripe — verifies Stripe-Signature header with timestamp validation (rejects replays >5 min old)
• generic-hmac — configurable header name and algorithm. Set algorithm (e.g., "sha256") and headerName (e.g., "X-Signature")

Free tier: 1 signing secret per hook. Pro tier: Up to 5 secrets for key rotation — all secrets are tried until one matches.

Set "debug": true during setup to see detailed error messages in 401 responses. Set to false for production (generic error only).

Disable Signature Validation

curl -X DELETE https://hookpipe.app/api/hooks/HOOK_ID/signature \
  -H "Authorization: Bearer YOUR_API_KEY"

Retry Policy

Failed forwarding attempts are retried automatically with exponential backoff.

• Free tier: 3 retries, 1-second fixed backoff
• Pro tier: Up to 10 retries with configurable interval (500ms–60s)

Configure Retry Policy (Pro)

curl -X PATCH https://hookpipe.app/api/hooks/HOOK_ID/retry \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxRetries": 7, "intervalMs": 5000}'

Limits & Notes

• Rate limit returns HTTP 429 with RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers
• Client errors (4xx) from your destination are not retried
• Signing secrets are encrypted at rest with AES-256-GCM