Queue Tables

webhook_queue

Pending Ultravox webhook events waiting to be processed. Events are enqueued by webhook-ingest and dequeued by process-webhook-queue (cron).

Column	Type	Default	Nullable	Description
id	uuid	uuid_generate_v4()	no	Primary key
agency_id	uuid	—	no	FK → agencies.id
event_type	varchar(50)	—	no	Ultravox event type (e.g., call.started, call.ended)
payload	jsonb	—	no	Full webhook event payload
status	processing_status	'pending'	no	Processing state
attempts	integer	0	no	Number of processing attempts
max_attempts	integer	5	no	Maximum retries before permanent failure
error_message	text	—	yes	Last error message
created_at	timestamptz	now()	no	When the event was received
processing_started_at	timestamptz	—	yes	When processing began
processed_at	timestamptz	—	yes	When processing completed
next_retry_at	timestamptz	—	yes	When to retry after a failure

Constraints:

Constraint	Type	Details
webhook_queue_pkey	Primary key	id
webhook_queue_agency_id_fkey	Foreign key	agency_id → agencies(id) ON DELETE CASCADE
webhook_queue_max_attempts	Check	attempts <= max_attempts

Indexes:

Index	Columns	Notes
idx_webhook_queue_pending	created_at	Filtered: WHERE status = 'pending' — FIFO dequeue
idx_webhook_queue_retry	next_retry_at	Filtered: WHERE status = 'failed' AND attempts < max_attempts — retryable items
idx_webhook_queue_agency	agency_id	Agency-scoped queries
idx_webhook_queue_status	status	Status monitoring
idx_webhook_queue_processed	processed_at	Filtered: WHERE status = 'completed' — cleanup queries

Related edge functions: webhook-ingest (enqueues), process-webhook-queue (dequeues)

---

webhook_logs

Audit trail for all incoming webhook requests, including validation failures.

Column	Type	Default	Nullable	Description
id	uuid	uuid_generate_v4()	no	Primary key
agency_id	uuid	—	yes	FK → agencies.id (null if agency lookup failed)
request_method	varchar(10)	'POST'	no	HTTP method of the webhook request
request_path	text	—	no	URL path of the request
request_headers	jsonb	—	yes	Request headers (sanitized)
request_body	jsonb	—	yes	Request body payload
validation_success	boolean	—	no	Whether webhook validation passed
validation_error	text	—	yes	Validation failure reason
queue_item_id	uuid	—	yes	FK → webhook_queue.id (if enqueued)
received_at	timestamptz	now()	no	When the request was received
source_ip	inet	—	yes	IP address of the sender

Constraints:

Constraint	Type	Details
webhook_logs_pkey	Primary key	id
webhook_logs_agency_id_fkey	Foreign key	agency_id → agencies(id) ON DELETE CASCADE

Indexes:

Index	Columns	Notes
idx_webhook_logs_agency	(agency_id, received_at DESC)	Agency webhook history
idx_webhook_logs_received	received_at DESC	Chronological listing
idx_webhook_logs_failed	received_at DESC	Filtered: WHERE validation_success = false — failed requests

Related edge functions: webhook-ingest

---

enrichment_queue

Processing queue for call transcript fetching and AI analysis. Items are created by database triggers and processed by process-enrichment-queue (cron).

Column	Type	Default	Nullable	Description
id	uuid	uuid_generate_v4()	no	Primary key
call_id	uuid	—	no	FK → calls.id
type	enrichment_type	—	no	transcript or analysis
status	processing_status	'pending'	no	Processing state
attempts	integer	0	no	Number of processing attempts
max_attempts	integer	3	no	Maximum retries
error_message	text	—	yes	Last error message
priority	integer	100	no	Priority (lower = higher priority)
created_at	timestamptz	now()	no	When the item was queued
processing_started_at	timestamptz	—	yes	When processing began
processed_at	timestamptz	—	yes	When processing completed
next_retry_at	timestamptz	—	yes	When to retry after a failure

Constraints:

Constraint	Type	Details
enrichment_queue_pkey	Primary key	id
enrichment_queue_unique_pending	Unique	(call_id, type, status) — prevents duplicate pending items
enrichment_queue_call_id_fkey	Foreign key	call_id → calls(id) ON DELETE CASCADE
enrichment_queue_max_attempts	Check	attempts <= max_attempts

Indexes:

Index	Columns	Notes
idx_enrichment_queue_pending	(priority, created_at)	Filtered: WHERE status = 'pending' — priority-ordered dequeue
idx_enrichment_queue_retry	next_retry_at	Filtered: WHERE status = 'failed' AND attempts < max_attempts — retryable items
idx_enrichment_queue_call	call_id	Items for a specific call
idx_enrichment_queue_type	type	Filter by enrichment type
idx_enrichment_queue_status	status	Status monitoring
idx_enrichment_queue_processed	processed_at	Filtered: WHERE status = 'completed' — cleanup queries

Related edge functions: process-enrichment-queue

Trigger-based creation: Items are automatically inserted by database triggers on the calls table:

1. call_ended_queue_transcript — inserts a transcript item when a call ends
2. transcript_fetched_queue_analysis — inserts an analysis item when the transcript is fetched