Basics & Terminology

Essential concepts and terminology to help you understand and use the hookVM platform effectively.

Core Concepts

What is a Webhook?

A webhook is an HTTP callback—a way for one application to send real-time data to another application when a specific event occurs.

Example: When a customer makes a payment on Stripe, Stripe sends a webhook to your application with the payment details.

Key Characteristics:

Event-driven: Triggered by specific events
Real-time: Data sent immediately when event occurs
HTTP POST: Typically uses POST requests with JSON payload
One-way: Sender doesn't wait for response (fire-and-forget)

hookVM Products

Flow

Purpose: Receive and route incoming webhooks from external services.

Use When: You need to receive webhooks from third-party APIs like Stripe, GitHub, or partner systems.

Key Terms:

Endpoint: A unique URL that receives webhooks
Relay Rule: Configuration to forward webhooks to your systems
Transformation: Modify webhook payload before forwarding

Example Flow:

Stripe → hookVM Endpoint → Your Backend API

Pulse

Purpose: Send webhooks to your customers or external systems.

Use When: You want to notify customers or partners when events happen in your application.

Key Terms:

Event Type: Category of event (e.g., order.created)
Subscription: Customer's registration to receive specific event types
Delivery: Attempt to send webhook to subscriber endpoint

Example Flow:

Your App → hookVM Pulse → Customer Webhook URL

Play

Purpose: Test, debug, and monitor webhook traffic in real-time.

Use When: You need to inspect webhook payloads, debug issues, or replay events.

Key Terms:

Request: Incoming webhook captured by hookVM
Payload: The JSON data sent in the webhook
Replay: Re-send a historical webhook event

Platform Terminology

Endpoints

Definition: A unique URL that receives webhook requests.

Format: https://hooks.hookvm.com/ep_abc123xyz

Configuration Options:

Source Type

Select the webhook source for automatic signature verification:

Generic Webhook: Standard webhook endpoint (no automatic verification)
Supported Providers: Select from available providers (e.g., Stripe, GitHub, Slack, and more)

Note: When you select a supported provider (not Generic), signature verification is automatically enabled to ensure webhook authenticity. We're constantly adding support for more providers.

Signature Verification

Purpose: Verify that webhooks actually come from the claimed source.

How It Works:

Select a source type (e.g., Stripe, GitHub, Slack)
Signature verification is automatically enabled
Enter your webhook secret key from the source
hookVM validates every incoming webhook signature
Invalid signatures are rejected automatically

Example (Stripe):

Source Type: Stripe
Enable Signature Verification: ✓ (auto-enabled)
Secret Key: whsec_abc123... (from Stripe dashboard)

Benefits:

✅ Prevents webhook spoofing
✅ Ensures data integrity
✅ Automatic validation (no code needed)
✅ Rejects unauthorized requests

Retention Days

Definition: How long to store webhook request data.

Range: 1-60 days

Default: 30 days

Use Cases:

Short retention (7 days): High-volume endpoints, privacy-sensitive data
Medium retention (30 days): Standard use cases, debugging
Long retention (60 days): Compliance, audit trails, historical analysis

Example:

Retention Days: 30

Note: After the retention period, webhook requests are automatically deleted. Plan accordingly for compliance and debugging needs.

Use Cases:

Receive webhooks from Stripe, GitHub, etc.
Create dedicated endpoints for different services
Separate staging and production webhooks
Automatic signature verification for security

Example:

# Your Stripe endpoint with signature verification
https://hooks.hookvm.com/ep_stripe_payments

# Your GitHub endpoint with automatic validation
https://hooks.hookvm.com/ep_github_events

Relay Rules

Definition: Configuration that forwards incoming webhooks to your systems.

Components:

Destination URL: Where to forward the webhook
HTTP Method: Usually POST
Headers: Authentication and custom headers
Filters: Conditions to apply before forwarding

Example Configuration:

{
  "destination": "https://api.yourapp.com/webhooks/stripe",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json"
  },
  "filter": {
    "type": "payment_intent.succeeded"
  }
}

Use Cases:

Forward to your backend API
Fan-out to multiple systems
Filter specific event types
Transform payloads

Event Types

Definition: Categories of events that your application can send via Pulse.

Naming Convention: Use dot notation (e.g., resource.action)

Examples:

order.created - New order placed
order.updated - Order status changed
order.cancelled - Order cancelled
user.created - New user registered
payment.succeeded - Payment completed

Schema: Define the structure of data for each event type

{
  "event_type": "order.created",
  "schema": {
    "order_id": "string",
    "customer_id": "string",
    "amount": "number",
    "currency": "string",
    "items": "array"
  }
}

Subscriptions

Definition: A customer's registration to receive specific event types.

Components:

Subscriber: The customer/system receiving webhooks
Event Types: Which events they want to receive
Endpoint URL: Where to send the webhooks
Authentication: Headers or secrets for verification

Example:

{
  "subscriber_id": "cus_abc123",
  "event_types": ["order.created", "order.updated"],
  "endpoint_url": "https://customer.com/webhooks",
  "headers": {
    "X-API-Key": "customer-api-key"
  }
}

Lifecycle:

Customer creates subscription
Your app sends events
hookVM delivers to subscriber
Retries on failure
Customer can pause/cancel subscription

Events

Definition: An occurrence in your application that triggers webhook delivery.

Structure:

{
  "id": "evt_abc123",
  "event_type": "order.created",
  "data": {
    "order_id": "ord_456",
    "customer_id": "cus_789",
    "amount": 99.99,
    "currency": "USD"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Properties:

ID: Unique identifier for the event
Event Type: Category of event
Data: Payload containing event details
Timestamp: When event occurred
Idempotency Key: Prevents duplicate processing

Deliveries

Definition: Attempts to send a webhook to a subscriber endpoint.

Status Types:

Queued: Waiting to be sent
Sending: Currently being delivered
Delivered: Successfully sent (2xx response)
Failed: Delivery failed (non-2xx response or timeout)
Retrying: Will retry after backoff period

Retry Logic:

Attempt 1: Immediate
Attempt 2: After 1 minute
Attempt 3: After 5 minutes
Attempt 4: After 15 minutes
Attempt 5: After 1 hour

Example:

{
  "delivery_id": "del_abc123",
  "event_id": "evt_456",
  "subscription_id": "sub_789",
  "status": "delivered",
  "attempts": 1,
  "response_code": 200,
  "delivered_at": "2024-01-15T10:30:01Z"
}

Requests

Definition: Incoming webhook captured by a Flow endpoint.

Contains:

Headers: HTTP headers from sender
Body: Payload (usually JSON)
Metadata: Timestamp, IP address, user agent
Response: Your system's response (if relayed)

Example Request:

POST /ep_abc123 HTTP/1.1
Host: hooks.hookvm.com
Content-Type: application/json
X-Stripe-Signature: t=1234567890,v1=abc...

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_123",
      "amount": 9999,
      "currency": "usd"
    }
  }
}

Transformations

Definition: Modify webhook payloads before forwarding or delivering.

Use Cases:

Simplify complex payloads
Add/remove fields
Rename properties
Convert formats

Example:

// Input (from Stripe)
{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_123",
      "amount": 9999
    }
  }
}

// Transform
function transform(input) {
  return {
    event: "payment_success",
    payment_id: input.data.object.id,
    amount_usd: input.data.object.amount / 100
  };
}

// Output (to your backend)
{
  "event": "payment_success",
  "payment_id": "pi_123",
  "amount_usd": 99.99
}

Filters

Definition: Conditions that determine whether to process a webhook.

Filter Types:

Event Type: Match specific event types
Field Value: Match field values in payload
Pattern: Regex or wildcard matching

Examples:

Simple Filter (event type):

{
  "type": "payment_intent.succeeded"
}

Complex Filter (field value):

{
  "type": "payment_intent.succeeded",
  "data.object.amount": { "$gt": 10000 }
}

Wildcard Filter:

{
  "type": "order.*"  // Matches order.created, order.updated, etc.
}

Authentication & Security

API Keys

Definition: Secret tokens used to authenticate API requests.

Format: hvm_sk_live_abc123... (live) or hvm_sk_test_abc123... (test)

Usage:

curl -H "Authorization: Bearer hvm_sk_live_abc123..." \
  https://api.hookvm.com/v1/events

Best Practices:

Never commit to version control
Rotate regularly
Use environment variables
Separate keys for dev/staging/production

Webhook Signatures

Definition: Cryptographic signatures to verify webhook authenticity.

Purpose: Ensure webhooks actually came from hookVM (not attackers)

Verification Process:

hookVM signs webhook with secret key
Sends signature in X-HookVM-Signature header
Your app verifies signature using shared secret
Reject if signature doesn't match

Example Verification (Node.js):

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return signature === expectedSignature;
}

Idempotency Keys

Definition: Unique identifiers to prevent duplicate event processing.

Purpose: Ensure events are processed exactly once, even if sent multiple times.

Usage:

await client.events.create({
  eventType: 'order.created',
  data: { order_id: 'ord_123' },
  idempotencyKey: 'ord_123_created'  // Same key = same event
});

Behavior:

First request: Creates new event
Duplicate request (same key): Returns original event, doesn't create new one

CLI Terminology

Listen

Definition: Monitor a hookVM endpoint and optionally forward to localhost.

Command:

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

What It Does:

Connects to hookVM endpoint
Streams incoming webhooks in real-time
Forwards to your local development server
Displays request/response details

Target

Definition: Local URL where CLI forwards webhooks.

Examples:

# Forward to port 3000
--target http://localhost:3000

# Forward to specific path
--target http://localhost:3000/webhooks/stripe

# Forward to different port
--target http://localhost:8080

Tunnel

Definition: Secure connection between hookVM and your localhost.

How It Works:

CLI establishes WebSocket connection to hookVM
Webhooks sent to your endpoint
hookVM streams to CLI over WebSocket
CLI forwards to your localhost
Response sent back through tunnel

Benefits:

No ngrok or public URLs needed
Secure (encrypted connection)
Works behind firewalls
No port forwarding required

Common Patterns

Fan-Out

Definition: Send one incoming webhook to multiple destinations.

Example:

Stripe Webhook → hookVM Endpoint
                    ├→ Backend API
                    ├→ Analytics Service
                    └→ Notification Service

Use Cases:

Send to multiple microservices
Separate processing and analytics
Notify multiple systems

Fan-In

Definition: Receive webhooks from multiple sources into one system.

Example:

Stripe Endpoint   ─┐
GitHub Endpoint   ─┤→ Your Backend API
SendGrid Endpoint ─┘

Use Cases:

Centralized webhook processing
Unified event handling
Single integration point

Event Sourcing

Definition: Store all events as immutable log for replay and audit.

hookVM Support:

All events stored permanently
Replay historical events
Audit trail for compliance
Event history search

Next Steps

Now that you understand the terminology:

Usage Examples - See these concepts in action
Getting Started Guide - Platform walkthrough
CLI Reference - Command-line tools

Questions? Contact support or check our FAQ

Core Concepts​

What is a Webhook?​

hookVM Products​

Flow​

Pulse​

Play​

Platform Terminology​

Endpoints​

Source Type​

Signature Verification​

Retention Days​

Relay Rules​

Event Types​

Subscriptions​

Events​

Deliveries​

Requests​

Transformations​

Filters​

Authentication & Security​

API Keys​

Webhook Signatures​

Idempotency Keys​

CLI Terminology​

Listen​

Target​

Tunnel​

Common Patterns​

Fan-Out​

Fan-In​

Event Sourcing​

Next Steps​

Core Concepts

What is a Webhook?

hookVM Products

Flow

Pulse

Play

Platform Terminology

Endpoints

Source Type

Signature Verification

Retention Days

Relay Rules

Event Types

Subscriptions

Events

Deliveries

Requests

Transformations

Filters

Authentication & Security

API Keys

Webhook Signatures

Idempotency Keys

CLI Terminology

Listen

Target

Tunnel

Common Patterns

Fan-Out

Fan-In

Event Sourcing

Next Steps