Skip to main content

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