Common Usage Examples

Practical, copy-paste examples for the most common hookVM use cases.

Example 1: Receiving Webhooks from External Services

Receive webhooks from third-party services like Stripe, GitHub, or any API provider.

Setup

Create an endpoint in the Flow section
- Name: Give it a descriptive name (e.g., "Payment Webhooks")
- Source Type: Select your webhook provider from the dropdown
- Signature Verification: Automatically enabled when you select a provider
- Secret Key: Enter your webhook secret from the provider
- Retention Days: Set how long to keep webhook data (1-60 days, default: 30)
Copy your endpoint URL: https://hooks.hookvm.com/ep_abc123
Add to external service webhook settings

Security Tip: When you select a supported provider, hookVM automatically verifies webhook signatures using the secret key you provide. This ensures webhooks are authentic and haven't been tampered with.

Configure in External Service

Example Configuration:

Webhook URL: https://hooks.hookvm.com/ep_abc123
Events: Select the events you want to receive
Signing Secret: Copy this to hookVM's "Secret Key" field

💡 Provider-Specific Instructions: Each provider has different webhook settings. Check your provider's documentation for exact field names and locations.

Verify Receipt

View incoming webhooks in the Play section:

Real-time event stream
Full payload inspection
Request headers and metadata
Signature verification status

📚 Learn more about creating endpoints →

Example 2: Fan-Out to Multiple Destinations

Route a single incoming webhook to multiple internal systems simultaneously.

Scenario

Receive a payment webhook from Stripe and send it to:

Your backend API
Analytics service
Notification service

Setup Relay Rules

Create endpoint for Stripe webhooks
Add relay rules in the endpoint settings:

Rule 1: Backend API

Destination: https://api.yourapp.com/webhooks/stripe
Method: POST
Headers: 
  Authorization: Bearer your-api-key
  Content-Type: application/json

Rule 2: Analytics

Destination: https://analytics.yourapp.com/events
Method: POST
Headers:
  X-API-Key: analytics-key

Rule 3: Notifications

Destination: https://notifications.yourapp.com/webhook
Method: POST
Headers:
  X-Service: stripe-webhooks

With Filtering

Send only successful payments to analytics:

{
  "filter": {
    "type": "payment_intent.succeeded"
  },
  "destination": "https://analytics.yourapp.com/events"
}

Result

One webhook from Stripe → Three destinations automatically:

✅ Backend processes payment
✅ Analytics tracks conversion
✅ Notification sent to customer

📚 Learn more about relay rules →

Example 3: Tunnel Webhooks to Localhost

Test webhooks on your local development environment without exposing your machine to the internet.

Install CLI

npm install -g @hookvm/cli

Authenticate

hookvm login

Start Tunneling

Basic forwarding:

hookvm listen https://hooks.hookvm.com/ep_abc123 --target http://localhost:3000

With custom path:

hookvm listen https://hooks.hookvm.com/ep_abc123 --target http://localhost:3000/webhooks/stripe

With headers:

hookvm listen https://hooks.hookvm.com/ep_abc123 \
  --target http://localhost:3000 \
  --header "X-Custom-Header: value"

What You See

🔗 Listening to: https://hooks.hookvm.com/ep_abc123
📍 Forwarding to: http://localhost:3000

[2024-01-15 10:30:45] POST /webhooks/stripe
  Status: 200 OK
  Latency: 45ms
  
  Headers:
    Content-Type: application/json
    X-Stripe-Signature: t=1234567890,v1=abc...
  
  Body:
    {
      "type": "payment_intent.succeeded",
      "data": { ... }
    }

Development Workflow

Start your local server:
```
npm run dev  # Runs on localhost:3000
```

Start hookVM tunnel:

hookvm listen https://hooks.hookvm.com/ep_abc123 --target http://localhost:3000

Configure external service to send webhooks to your hookVM endpoint
Develop and test - webhooks arrive at your localhost in real-time

Benefits

✅ No ngrok or tunnel services needed
✅ Secure - your machine stays private
✅ Real-time debugging
✅ Works with any local port

📚 Learn more about CLI →

Example 4: Sending Webhooks via API

Send webhooks to your customers programmatically using the hookVM API.

Setup

Create event type in Pulse section:
- Name: order.created
- Schema: Define your payload structure
Customer creates subscription to your event type
Generate API key in API Keys section

Send Event via cURL

curl -X POST https://api.hookvm.com/v1/events \
  -H "Authorization: Bearer hvm_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "order.created",
    "data": {
      "order_id": "ord_12345",
      "customer_id": "cus_67890",
      "amount": 99.99,
      "currency": "USD",
      "items": [
        {
          "product_id": "prod_111",
          "quantity": 2,
          "price": 49.99
        }
      ],
      "created_at": "2024-01-15T10:30:00Z"
    },
    "idempotency_key": "ord_12345_created"
  }'

Response

{
  "id": "evt_abc123",
  "event_type": "order.created",
  "status": "queued",
  "created_at": "2024-01-15T10:30:01Z",
  "delivery_count": 3
}

Example 5: Sending Webhooks via SDK

Use official SDKs for easier integration.

Node.js

Install:

npm install @hookvm/node

Usage:

const { HookVM } = require('@hookvm/node');

const client = new HookVM({
  apiKey: process.env.HOOKVM_API_KEY
});

// Send event
async function notifyOrderCreated(order) {
  try {
    const event = await client.events.create({
      eventType: 'order.created',
      data: {
        order_id: order.id,
        customer_id: order.customer_id,
        amount: order.total,
        currency: 'USD',
        items: order.items,
        created_at: new Date().toISOString()
      },
      idempotencyKey: `order_${order.id}_created`
    });
    
    console.log('Event sent:', event.id);
    return event;
  } catch (error) {
    console.error('Failed to send webhook:', error);
    throw error;
  }
}

// Usage in your application
app.post('/orders', async (req, res) => {
  const order = await createOrder(req.body);
  
  // Send webhook notification
  await notifyOrderCreated(order);
  
  res.json({ order });
});

Python

Install:

pip install hookvm

Usage:

from hookvm import HookVM
import os
from datetime import datetime

client = HookVM(api_key=os.environ['HOOKVM_API_KEY'])

# Send event
def notify_order_created(order):
    try:
        event = client.events.create(
            event_type='order.created',
            data={
                'order_id': order.id,
                'customer_id': order.customer_id,
                'amount': order.total,
                'currency': 'USD',
                'items': order.items,
                'created_at': datetime.utcnow().isoformat()
            },
            idempotency_key=f'order_{order.id}_created'
        )
        
        print(f'Event sent: {event.id}')
        return event
    except Exception as error:
        print(f'Failed to send webhook: {error}')
        raise

# Usage in your application
@app.route('/orders', methods=['POST'])
def create_order():
    order = create_order_from_request(request.json)
    
    # Send webhook notification
    notify_order_created(order)
    
    return jsonify({'order': order.to_dict()})

Go

Install:

go get github.com/hookvm/hookvm-go

Usage:

package main

import (
    "context"
    "fmt"
    "os"
    "time"
    
    "github.com/hookvm/hookvm-go"
)

func main() {
    client := hookvm.NewClient(os.Getenv("HOOKVM_API_KEY"))
    
    // Send event
    event, err := client.Events.Create(context.Background(), &hookvm.EventCreateParams{
        EventType: "order.created",
        Data: map[string]interface{}{
            "order_id":    "ord_12345",
            "customer_id": "cus_67890",
            "amount":      99.99,
            "currency":    "USD",
            "items": []map[string]interface{}{
                {
                    "product_id": "prod_111",
                    "quantity":   2,
                    "price":      49.99,
                },
            },
            "created_at": time.Now().Format(time.RFC3339),
        },
        IdempotencyKey: "ord_12345_created",
    })
    
    if err != nil {
        fmt.Printf("Failed to send webhook: %v\n", err)
        return
    }
    
    fmt.Printf("Event sent: %s\n", event.ID)
}

SDK Features

All SDKs include:

✅ Automatic retries
✅ Idempotency support
✅ Type safety (TypeScript, Go)
✅ Error handling
✅ Batch operations
✅ Event querying

📚 View SDK documentation →

Example 6: Batch Sending Webhooks

Send multiple events efficiently.

Node.js Batch Example

const { HookVM } = require('@hookvm/node');

const client = new HookVM({
  apiKey: process.env.HOOKVM_API_KEY
});

async function notifyBulkOrderUpdates(orders) {
  const events = orders.map(order => ({
    eventType: 'order.updated',
    data: {
      order_id: order.id,
      status: order.status,
      updated_at: new Date().toISOString()
    },
    idempotencyKey: `order_${order.id}_updated_${Date.now()}`
  }));
  
  // Send in batch
  const results = await client.events.createBatch(events);
  
  console.log(`Sent ${results.length} events`);
  return results;
}

// Process 100 orders
const orders = await getOrdersToUpdate();
await notifyBulkOrderUpdates(orders);

API Batch Example

curl -X POST https://api.hookvm.com/v1/events/batch \
  -H "Authorization: Bearer hvm_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_type": "order.updated",
        "data": { "order_id": "ord_1", "status": "shipped" }
      },
      {
        "event_type": "order.updated",
        "data": { "order_id": "ord_2", "status": "delivered" }
      },
      {
        "event_type": "order.updated",
        "data": { "order_id": "ord_3", "status": "cancelled" }
      }
    ]
  }'

Example 7: Webhook Transformation

Transform incoming webhook payloads before forwarding.

Scenario

Receive Stripe webhooks but forward simplified data to your backend.

Transformation Rule

Input (from Stripe):

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_123",
      "amount": 9999,
      "currency": "usd",
      "customer": "cus_456",
      "metadata": {
        "order_id": "ord_789"
      }
    }
  }
}

Transform to:

{
  "event": "payment_success",
  "payment_id": "pi_123",
  "amount_usd": 99.99,
  "customer_id": "cus_456",
  "order_id": "ord_789"
}

Configure in Flow

Create endpoint for Stripe
Add transformation rule:

// Transformation function
function transform(payload) {
  return {
    event: 'payment_success',
    payment_id: payload.data.object.id,
    amount_usd: payload.data.object.amount / 100,
    customer_id: payload.data.object.customer,
    order_id: payload.data.object.metadata.order_id
  };
}

Set relay destination to your backend

📚 Learn more about transformations →

Next Steps

Learn More

Flow Documentation - Complete Flow product guide
CLI Reference - All CLI commands
Best Practices - Production recommendations

Get Help

Email: support@hookvm.com
Status: status.hookvm.com

Ready to implement? Create your free account →

Example 1: Receiving Webhooks from External Services​

Setup​

Configure in External Service​

Verify Receipt​

Example 2: Fan-Out to Multiple Destinations​

Scenario​

Setup Relay Rules​

With Filtering​

Result​

Example 3: Tunnel Webhooks to Localhost​

Install CLI​

Authenticate​

Start Tunneling​

What You See​

Development Workflow​

Benefits​

Example 4: Sending Webhooks via API​

Setup​

Send Event via cURL​

Response​

Example 5: Sending Webhooks via SDK​

Node.js​

Python​

Go​

SDK Features​

Example 6: Batch Sending Webhooks​

Node.js Batch Example​

API Batch Example​

Example 7: Webhook Transformation​

Scenario​

Transformation Rule​

Configure in Flow​

Next Steps​

Learn More​

Get Help​

Example 1: Receiving Webhooks from External Services

Setup

Configure in External Service

Verify Receipt

Example 2: Fan-Out to Multiple Destinations

Scenario

Setup Relay Rules

With Filtering

Result

Example 3: Tunnel Webhooks to Localhost

Install CLI

Authenticate

Start Tunneling

What You See

Development Workflow

Benefits

Example 4: Sending Webhooks via API

Setup

Send Event via cURL

Response

Example 5: Sending Webhooks via SDK

Node.js

Python

Go

SDK Features

Example 6: Batch Sending Webhooks

Node.js Batch Example

API Batch Example

Example 7: Webhook Transformation

Scenario

Transformation Rule

Configure in Flow

Next Steps

Learn More

Get Help