Data Model

This document explains the core data entities in Unhook and how they relate to each other.

Entity Relationships

Core Entities

Webhook Entity

The primary entity that manages webhook routing and configuration.
id
string
required
Unique identifier with ‘t’ prefix
clientId
string
required
Client identifier for routing
webhookId
string
required
Associated webhook ID
port
number
required
Local port to deliver requests to
status
string
required
Current webhook status. Can be ‘active’ or ‘inactive’
localConnectionStatus
string
required
Connection status. Can be ‘connected’ or ‘disconnected’
config
object
required
Webhook configuration object
{
  storage: {
    storeHeaders: boolean;
    storeRequestBody: boolean;
    storeResponseBody: boolean;
    maxRequestBodySize: number;  // in bytes
    maxResponseBodySize: number; // in bytes
  };
  headers: {
    allowList?: string[];       // Only store these headers
    blockList?: string[];       // Never store these headers
    sensitiveHeaders?: string[]; // Replace with "[REDACTED]"
  };
  requests: {
    allowedMethods?: string[];  // Only allow specific HTTP methods
    allowedFrom?: string[];    // Only allow specific paths
    blockedFrom?: string[];    // Block specific paths
    maxRequestsPerMinute?: number;
    maxRetries?: number;
  };
}
userId
string
required
Owner user ID
orgId
string
required
Organization ID

Event Entity

Represents a webhook notification received by the system.
id
string
required
Unique identifier with ‘evt’ prefix
webhookId
string
required
Associated webhook ID
originalRequest
object
required
Original incoming webhook data (RequestPayload)
status
string
required
Current status. Can be ‘pending’, ‘processing’, ‘completed’, or ‘failed’
retryCount
number
required
Number of retry attempts made
maxRetries
number
required
Maximum allowed retries
failedReason
string
Failure explanation if applicable
timestamp
string
required
When the event was received (ISO date string)

Request Entity

Represents an attempt to deliver a webhook to a local development environment.
id
string
required
Unique identifier with ‘req’ prefix
webhookId
string
required
Associated webhook ID
eventId
string
required
Associated event ID
webhookId
string
required
Associated webhook ID
connectionId
string
Active connection ID if applicable
request
object
required
Request details (RequestPayload)
status
string
required
Current status. Can be ‘pending’, ‘completed’, or ‘failed’
response
object
Response if completed (ResponsePayload)
responseTimeMs
number
required
Response time in milliseconds
timestamp
string
required
When the request was made (ISO date string)
completedAt
string
When the request completed (ISO date string)

RequestPayload Entity

id
string
required
Unique request identifier
method
string
required
HTTP method used
url
string
required
Request URL
headers
object
required
HTTP headers as key-value pairs
size
number
required
Request size in bytes
body
string
Base64 encoded request body
timestamp
number
required
Unix timestamp of the request
contentType
string
required
Content-Type of the request
clientIp
string
required
IP address of the client

Data Flow

1

Webhook Reception

  • System creates an Event with the original request
  • Event is associated with the target Webhook
  • Initial status is set to ‘pending’
2

Processing

  • System creates a Request for delivery attempt
  • Request inherits Event and Webhook properties
  • System attempts to deliver to local environment
3

Completion

  • Request status updated to ‘completed’ or ‘failed’
  • Event status updated based on Request outcome
  • If failed and retries available, new Request created

Security Considerations

API Keys

API keys are required for webhook reception and authentication

Header Protection

Sensitive headers can be redacted via configuration

Size Limits

Request/response body size limits enforced

Organization Isolation

Organization-level isolation of data

Access Control

User-level access control to resources