Core Concepts

Understand the fundamental concepts that power HookWatch. This guide explains how webhooks flow through the system and the terminology used throughout the documentation.

Webhooks

Webhooks are HTTP callbacks that notify your application when events happen in external services. Instead of polling an API repeatedly, webhooks push data to your server in real-time.

External Service (Stripe, GitHub, etc.)
         │
         │ Webhook (HTTP POST)
         ▼
    ┌──────────┐
    │ HookWatch │ ◄── Receives, logs, and forwards
    └────┬─────┘
         │
         │ Forward (HTTP POST)
         ▼
    Your Server

Endpoints

An endpoint is a webhook receiver configured in HookWatch. Each endpoint has a unique URL where external services send webhooks.

Webhook URL

https://hook.hookwatch.dev/:slug

The URL you give to external services. Each endpoint has a unique slug.

Destination URL

https://your-server.com/webhooks

Where HookWatch forwards the webhook. This is your actual server.

Events

An event represents a single webhook received by HookWatch. Each event contains the complete request data and tracks the delivery status.

Event Data

  • HTTP method, headers, and body
  • Source IP address
  • Timestamp of receipt
  • Delivery status and response

Delivery Lifecycle

Every event goes through a delivery lifecycle from receipt to final delivery or failure.

Pending

Webhook received, queued for delivery. Initial state before first delivery attempt.

Delivery attempt...

Delivered

Successfully delivered to destination (2xx response received). Final success state.

— or —

Retrying

Delivery failed, scheduled for automatic retry. Retries follow configured intervals.

After max retries exhausted...

Failed

All retry attempts exhausted. Manual intervention required (retry or replay).

Retry Logic

When delivery fails, HookWatch automatically retries with exponential backoff.

Default Retry Schedule

1 min → 5 min → 30 min → 2 hours → 24 hours

Pro and Business plans can configure custom retry intervals.

Cron Jobs

Cron jobs let you schedule recurring shell commands that run locally on your CLI agent. Unlike webhooks (which are triggered by external events), cron jobs run on a schedule you define.

Webhooks

Push: External services trigger requests to your server

Cron Jobs

Schedule: CLI agents execute shell commands on a defined schedule

Agents

An agent is a registered CLI instance that executes cron jobs locally on its host machine. Each agent has a unique name and is tied to a hostname, with heartbeat monitoring to track availability.

Registration

Register your CLI as a named agent with hookwatch agent register my-server. The agent ID is stored in your config.

Execution

Agents run the cron service daemon to execute scheduled jobs, sync with the cloud, and respond to "Run Now" triggers from the dashboard.

Teams

Teams are multi-user workspaces that let you collaborate on webhook endpoints, cron jobs, and alerts. Team members share access to resources while maintaining individual authentication.

Glossary

Slug
Unique identifier in the webhook URL (e.g., abc123 in hook.hookwatch.dev/abc123)
Destination URL
Your server URL where webhooks are forwarded
Replay
Create a new event with the same payload as an existing event
Retry
Resend the original event without creating a new one
Buffer
Service that stores webhooks when your server is unavailable
Agent
A registered CLI instance that executes cron jobs locally on its host machine
Team
A shared workspace where multiple users collaborate on endpoints, cron jobs, and alerts

Related