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