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.string
required
Unique identifier with ‘t’ prefix
string
required
Client identifier for routing
string
required
Associated webhook ID
number
required
Local port to deliver requests to
string
required
Current webhook status. Can be ‘active’ or ‘inactive’
string
required
Connection status. Can be ‘connected’ or ‘disconnected’
object
required
Webhook configuration object
string
required
Owner user ID
string
required
Organization ID
Event Entity
Represents a webhook notification received by the system.string
required
Unique identifier with ‘evt’ prefix
string
required
Associated webhook ID
object
required
Original incoming webhook data (RequestPayload)
string
required
Current status. Can be ‘pending’, ‘processing’, ‘completed’, or ‘failed’
number
required
Number of retry attempts made
number
required
Maximum allowed retries
string
Failure explanation if applicable
string
required
When the event was received (ISO date string)
Request Entity
Represents an attempt to deliver a webhook to a local development environment.string
required
Unique identifier with ‘req’ prefix
string
required
Associated webhook ID
string
required
Associated event ID
string
required
Associated webhook ID
string
Active connection ID if applicable
object
required
Request details (RequestPayload)
string
required
Current status. Can be ‘pending’, ‘completed’, or ‘failed’
object
Response if completed (ResponsePayload)
number
required
Response time in milliseconds
string
required
When the request was made (ISO date string)
string
When the request completed (ISO date string)
RequestPayload Entity
string
required
Unique request identifier
string
required
HTTP method used
string
required
Request URL
object
required
HTTP headers as key-value pairs
number
required
Request size in bytes
string
Base64 encoded request body
number
required
Unix timestamp of the request
string
required
Content-Type of the request
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