Quick Start

About 539 wordsAbout 2 min

Get GetHook running locally and receive your first webhook in under 5 minutes.

Prerequisites

Docker and Docker Compose
curl and jq (for the examples below)

1. Start the stack

git clone https://github.com/gethook/gethook.git
cd gethook
cp .env.example .env
make docker-up

This starts:

Postgres on port 5432
API server on port 8080
Delivery worker (background process)
Docs on port 8085

Start the dashboard separately:

cd dashboard
echo "NEXT_PUBLIC_API_URL=http://localhost:8080" > .env.local
npm install && npm run dev

Dashboard is now at http://localhost:3000.

2. Create an account

curl -s -X POST http://localhost:8080/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{"name": "My Company"}' | jq .

Response:

{
  "data": {
    "account": {
      "id": "a1b2c3d4-...",
      "name": "My Company",
      "plan": "free",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "api_key": {
      "id": "k1k2k3k4-...",
      "name": "default",
      "key_prefix": "hk_ab12",
      "plain_key": "hk_ab12ef34..."
    }
  }
}

Save your API key

The plain_key is shown once. Copy it now — you cannot retrieve it again.

export API_KEY="hk_ab12ef34..."

3. Create a Source

A source is an inbound webhook endpoint. Use a provider preset to auto-configure signature verification:

# With Stripe preset (auto-configures Stripe-Signature header)
curl -s -X POST http://localhost:8080/v1/sources \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Events",
    "provider": "stripe",
    "verification_config": { "header": "Stripe-Signature", "secret": "whsec_abc123" }
  }' | jq .

Or create a plain source with no verification:

curl -s -X POST http://localhost:8080/v1/sources \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Source"}' | jq .

Note the ingest_url in the response — that's where you'll point your provider.

Supported provider presets: stripe, shopify, github, twilio, slack, linear, paddle, hubspot, sendgrid, woocommerce

4. Create a Destination

Use a destination preset to auto-configure delivery to popular services:

# Slack preset — posts to a channel via Incoming Webhooks
curl -s -X POST http://localhost:8080/v1/destinations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "#alerts",
    "url": "https://hooks.slack.com/services/T.../B.../...",
    "preset": "slack"
  }' | jq .

Or a plain custom endpoint:

curl -s -X POST http://localhost:8080/v1/destinations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "url": "https://webhook.site/your-unique-id",
    "timeout_seconds": 30
  }' | jq .

Supported destination presets: slack, discord, teams, pagerduty, datadog, hubspot, linear, notion, airtable, zapier, n8n, make

Test with webhook.site

Use webhook.site to get a free inspection URL while testing.

5. Create a Route

Connect the source to the destination:

curl -s -X POST http://localhost:8080/v1/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "<source-id-from-step-3>",
    "destination_id": "<destination-id-from-step-4>"
  }' | jq .

6. Send a test webhook

curl -s -X POST http://localhost:8080/ingest/<path-token-from-step-3> \
  -H "Content-Type: application/json" \
  -H "X-Event-Type: payment.succeeded" \
  -d '{"amount": 2000, "currency": "usd"}' | jq .

Response:

{
  "data": {
    "id": "evt_...",
    "status": "queued"
  }
}

The delivery worker picks this up within seconds and forwards it to your destination.

7. Check event status

curl -s http://localhost:8080/v1/events \
  -H "Authorization: Bearer $API_KEY" | jq .

End-to-end smoke test

The repo includes a full smoke test script:

make smoke

This automates steps 2–7 and verifies the full ingest → queue → delivery pipeline.