Webhook - Well Starter Kit

The Webhook entity represents webhook configurations in the Well system. It allows external systems to receive real-time notifications about events occurring within workspaces.

Table structure

Table name: webhooks

Main fields

Name	Type	Required	Constraints	Allowed Values	Description	Example
`id`	string, UUID, 🔒 system	✅ Yes	Unique identifier (read-only)	–	Unique identifier of the webhook	`”webhook-uuid-123”`
`workspace`	Workspace (UUID)	✅ Yes	Foreign key reference	–	Reference to the workspace	`”workspace-uuid-456”`
`url`	string	✅ Yes	valid URL format	–	Webhook endpoint URL	`”https://api.example.com/webhooks/well”`
`secret`	string	⚪ No	nullable	–	Webhook secret for signature verification	`”your-webhook-secret”`
`events`	string[]	✅ Yes	array of event types	document., company., person., workspace., collection.*	Array of subscribed event types	`[“document.created”, “document.updated”]`
`is_active`	boolean	⚪ No	default: true	`true`, `false`	Webhook active status	`true`
`retry_count`	number	⚪ No	default: 3, max: 10	0-10	Number of delivery retries	`3`
`timeout_ms`	number	⚪ No	default: 5000, max: 30000	1000-30000	Request timeout in milliseconds	`5000`
`last_delivery_at`	string (ISO 8601) 🔒 system	⚪ No	nullable timestamp	–	Last successful delivery timestamp	`”2024-01-15T10:30:00Z”`
`last_failure_at`	string (ISO 8601) 🔒 system	⚪ No	nullable timestamp	–	Last failure timestamp	`”2024-01-15T11:00:00Z”`
`failure_count`	number 🔒 system	⚪ No	default: 0	0+	Consecutive failure count	`0`
`created_at`	string (ISO 8601) 🔒 system	–	auto timestamp	–	Creation timestamp	`”2023-01-01T12:00:00Z”`
`updated_at`	string (ISO 8601) 🔒 system	–	auto timestamp	–	Last updated timestamp	`”2024-01-01T12:00:00Z”`
`deleted_at`	string \| null 🔒 system	⚪ No	nullable ISO 8601	–	Deletion timestamp (soft delete)	`“2024-01-01T12:00:00Z”`

Relations

Many-to-One relations

Workspace: The workspace that owns the webhook

Relationship schema

Webhook (N) ←→ (1) Workspace

# A workspace can have multiple webhooks
Workspace (1) ←→ (N) Webhook

Event types

Supported events

enum WebhookEventType {
  // Document events
  DOCUMENT_UPLOADED = 'document.uploaded',
  DOCUMENT_PROCESSED = 'document.processed',
  DOCUMENT_DELETED = 'document.deleted',
  
  // Company events
  COMPANY_CREATED = 'company.created',
  COMPANY_UPDATED = 'company.updated',
  COMPANY_DELETED = 'company.deleted',
  
  // Person events
  PERSON_CREATED = 'person.created',
  PERSON_UPDATED = 'person.updated',
  PERSON_DELETED = 'person.deleted',
  
  // Workspace events
  WORKSPACE_UPDATED = 'workspace.updated',
  
  // Collection events
  COLLECTION_FINALIZED = 'collection.finalized',
  COLLECTION_SENT = 'collection.sent'
}

Data Model

​Table structure

​Main fields

​Relations

​Many-to-One relations

​Relationship schema

​Event types

​Supported events