Getting Started

Welcome to HooksDash! This guide will help you understand webhooks, set up your account, and start using HooksDash for webhook development and testing.

Table of Contents

• What are Webhooks?
• What is HooksDash?
• Core Concepts
• Getting Started
• Best Practices
• Next Steps

What are Webhooks?

Webhooks are HTTP callbacks that allow services to send real-time notifications to your application when events occur.

How Webhooks Work

Copy
┌──────────────┐         Event Occurs          ┌──────────────┐
│   Service    │ ────────────────────────────> │ Your Server  │
│  (Stripe,    │  HTTP POST with event data    │              │
│   GitHub,    │ <──────────────────────────── │              │
│   etc.)      │      200 OK response          │              │
└──────────────┘                               └──────────────┘

Common Webhook Use Cases

• Payment Processing: Stripe sends webhooks when payments succeed/fail
• Git Events: GitHub sends webhooks for pushes, PRs, issues
• Messaging: Twilio sends webhooks for SMS replies, call status
• Email: SendGrid sends webhooks for email delivery, bounces
• E-commerce: Shopify sends webhooks for new orders, inventory changes

The Challenge

Developing with webhooks is difficult because:

1. Services require HTTPS: Most webhook providers require public HTTPS URLs
2. Local development is hard: Your localhost isn't accessible from the internet
3. Debugging is painful: You can't easily inspect webhook payloads
4. Testing is slow: Triggering real events takes time
5. Replay is impossible: You can't re-send the same webhook for testing

What is HooksDash?

HooksDash solves these problems by providing:

1. Instant Webhook URLs: Get a public HTTPS URL instantly
2. Request Inspection: See every detail of incoming webhooks
3. Local Forwarding: Forward webhooks to your localhost via CLI
4. Replay Functionality: Re-send any captured webhook to test your code
5. Request History: Keep a history of all webhook requests

Architecture

Copy
┌─────────────┐                    ┌──────────────┐
│  Webhook    │  1. Send webhook   │  HooksDash   │
│  Provider   ├───────────────────>│  Platform    │
│  (Stripe)   │                    │              │
└─────────────┘                    └───────┬──────┘
                                           │
                                  2. Store & Forward
                                           │
                                           v
                                   ┌───────────────┐
                                   │  Your Local   │
                                   │  Development  │
                                   │  Server       │
                                   └───────────────┘

Core Concepts

Endpoints

An endpoint is a unique URL that receives webhooks. https://hooksdash.ibadsiddiqui.dev/api/h/{your-slug}

• Each endpoint has a unique slug (e.g., stripe-dev, github-test)
• Endpoints can be activated/deactivated
• Each endpoint stores its own request history

Requests

A request is a captured webhook sent to your endpoint.

Captured data includes:

• HTTP method (POST, GET, etc.)
• Headers (including signature headers)
• Query parameters
• Request body
• Source IP address
• Timestamp

Tunnels (CLI)

A tunnel forwards webhooks from HooksDash to your local machine in real-time via WebSocket.

Copy
hooksdash forward --port 3000 --endpoint my-endpoint

Getting Started

1. Create an Account

1. Visit hooksdash.ibadsiddiqui.dev
2. Click "Sign Up"
3. Choose your authentication method:
   • Google
   • GitHub
   • Email + Password

2. Create Your First Endpoint

1. Click "New Endpoint"
2. Enter a name (e.g., "Stripe Development")
3. Specify a custom slug (Optional)
4. Add a description (Optional)
5. Click "Create"

3. Get Your API Key

1. Go to Settings → API Keys
2. Copy your API key (starts with hd_)

4. Install the CLI

Install the cli using the following command:

Copy
npm install -g hooksdash

Verify installation:

Copy
hooksdash --version

5. Authenticate the CLI

After successful installation, login using the command:

Copy
hooksdash login

This opens your browser for authentication. Alternatively, use your API key:

Copy
hooksdash login --api-key hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

6. Configure Your First Webhook

Let's use Stripe as an example:

1. Log in to Stripe Dashboard
2. Go to Developers → Webhooks
3. Click "Add endpoint"
4. Enter URL: https://hooksdash.ibadsiddiqui.dev/api/h/stripe-dev
5. Select events to send (e.g., payment_intent.succeeded)
6. Click "Add endpoint"

7. Test Your Webhook

Stripe provides a "Send test webhook" button:

1. In Stripe, click on your webhook endpoint
2. Click "Send test webhook"
3. Select an event type
4. Click "Send test webhook"

8. View in Dashboard

1. Go to HooksDash dashboard
2. Click on your endpoint
3. See your test webhook request
4. Click on it to inspect headers, body, etc.

9. Forward to Localhost

Start your local development server:

Copy
// server.js
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  console.log('Webhook received:', req.body);

  // Process the webhook
  const event = req.body;

  switch (event.type) {
    case 'payment_intent.succeeded':
      console.log('Payment succeeded!', event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  res.json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Start the server:

Copy
node server.js

Start the tunnel:

Copy
hooksdash forward --port 3000 --endpoint stripe-dev

Send another test webhook from Stripe - it will now reach your local server!

10. Replay Webhooks

To test your webhook handler without triggering real events:

1. Go to your endpoint
2. Click on a captured request
3. Click "Replay"
4. Enter target URL: http://localhost:3000/webhook
5. Click "Send"

Best Practices

1. Endpoint Organization

Create separate endpoints for:

• Different services (Stripe, GitHub, Twilio)
• Different environments (dev, staging, prod)
• Different applications

Good naming:

• stripe-production
• github-staging
• twilio-dev

Bad naming:

• endpoint1
• test
• abc123

2. Security

Verify webhook signatures:

Always verify that webhooks come from the expected source:

Copy
// Stripe example
const event = stripe.webhooks.constructEvent(
  req.body,
  req.headers['stripe-signature'],
  webhookSecret
);

Use HTTPS in production:

Never use HTTP endpoints in production - always HTTPS.

Rotate API keys regularly:

Regenerate your API keys periodically in Settings.

3. Error Handling

Return 2xx quickly:

Services expect a 2xx response within seconds:

Copy
app.post('/webhook', async (req, res) => {
  // Respond immediately
  res.json({ received: true });

  // Process asynchronously
  processWebhookAsync(req.body);
});

Implement retries:

Handle webhook processing failures gracefully:

Copy
async function processWebhookAsync(data) {
  for (let i = 0; i < 3; i++) {
    try {
      await processWebhook(data);
      break;
    } catch (err) {
      console.error(`Retry ${i + 1}/3 failed:`, err);
      await sleep(1000 * Math.pow(2, i)); // Exponential backoff
    }
  }
}

Log everything:

Keep detailed logs for debugging:

Copy
app.post('/webhook', (req, res) => {
  const requestId = generateId();

  console.log(`[${requestId}] Webhook received`);
  console.log(`[${requestId}] Headers:`, req.headers);
  console.log(`[${requestId}] Body:`, req.body);

  // Process...

  console.log(`[${requestId}] Processing complete`);
  res.json({ received: true });
});

4. Testing

Test locally first:

Use HooksDash CLI to test on localhost before deploying.

Use replay for edge cases:

Capture real webhooks, then replay with modified data:

Copy
# Replay with original data
curl -X POST /api/requests/req_xxx/replay \
  -d '{"url": "http://localhost:3000/webhook"}'

# Replay with modified data
curl -X POST /api/requests/req_xxx/replay \
  -d '{
    "url": "http://localhost:3000/webhook",
    "body": {
      "amount": 999999,
      "test_case": "large_amount"
    }
  }'

Implement idempotency:

Handle duplicate webhooks gracefully:

Copy
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.body.id;

  if (processedWebhooks.has(webhookId)) {
    console.log('Duplicate webhook, skipping');
    return res.json({ received: true });
  }

  processedWebhooks.add(webhookId);

  // Process webhook...

  res.json({ received: true });
});

5. Monitoring

Use monitoring tools to alert on webhook failures, high error rates, or unusual patterns.

Track webhook metrics:

Copy
let webhookCount = 0;
let errorCount = 0;

app.post('/webhook', async (req, res) => {
  webhookCount++;

  try {
    await processWebhook(req.body);
    res.json({ received: true });
  } catch (err) {
    errorCount++;
    console.error('Webhook processing failed:', err);
    res.status(500).json({ error: 'Processing failed' });
  }
});

// Log metrics periodically
setInterval(() => {
  console.log('Webhooks:', webhookCount, 'Errors:', errorCount);
}, 60000);

Next Steps

Explore the Dashboard

• View request details
• Filter and search requests
• Manage endpoints
• Check API usage

Read the Documentation

• 5-Minute Quickstart
• CLI Commands
• API Reference

Upgrade Your Account

Free tier limits:

• 3 endpoints
• 100 requests per endpoint
• 24-hour retention

Upgrade for:

• More endpoints
• Higher request limits
• Longer retention
• Priority support

Join the Community

• GitHub: github.com/hooksdash/hooksdash
• Discord: Join our Discord
• Twitter: @hooksdash

Get Support

• Email: support@hooksdash.ibadsiddiqui.dev
• Documentation: docs.hooksdash.ibadsiddiqui.dev
• GitHub Issues: Report bugs and request features

---

Ready to build? Start with the 5-Minute Quickstart or dive into the API Documentation.