Data Model

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

Assistant

Responses are generated using AI and may contain mistakes.