Inbox API

All inbox functions live in the tide schema.

tide.inbox_create

Create a named inbox with its message table.

SELECT tide.inbox_create(
  p_name                      TEXT,
  p_schema                    TEXT DEFAULT 'tide',
  p_max_retries               INT  DEFAULT 3,
  p_processed_retention_hours INT  DEFAULT 72,
  p_dlq_retention_hours       INT  DEFAULT 0
);

Creates: A table {schema}."{name}_inbox" with columns for dedup, retry tracking, and payload storage.

Example:

SELECT tide.inbox_create('payment-webhooks',
  p_max_retries := 5,
  p_processed_retention_hours := 168
);

tide.inbox_drop

Drop a named inbox and its message table.

SELECT tide.inbox_drop(
  p_name       TEXT,
  p_if_exists  BOOLEAN DEFAULT false
);

Cascades: Drops the inbox table and removes the config entry.

tide.inbox_mark_processed

Mark an inbox message as successfully processed.

SELECT tide.inbox_mark_processed(
  p_name      TEXT,
  p_event_id  TEXT
);

Sets processed_at = now() on the matching row. Idempotent — calling it on an already-processed message is a no-op.

tide.inbox_mark_failed

Mark an inbox message as failed. Increments retry_count and stores the error.

SELECT tide.inbox_mark_failed(
  p_name      TEXT,
  p_event_id  TEXT,
  p_error     TEXT
);

tide.inbox_status

Get status summary for an inbox (or all inboxes).

-- Single inbox
SELECT tide.inbox_status('payment-webhooks') → JSONB

-- All inboxes
SELECT tide.inbox_status() → JSONB

Returns (single inbox):

{
  "inbox_name": "payment-webhooks",
  "pending": 3,
  "dlq_count": 1
}

tide.replay_inbox_messages

Re-queue failed messages for reprocessing. Resets retry_count to 0 and clears last_error.

SELECT tide.replay_inbox_messages(
  p_name       TEXT,
  p_event_ids  TEXT[]
) → BIGINT

Returns: Number of messages successfully re-queued.

Example:

SELECT tide.replay_inbox_messages('payment-webhooks',
  ARRAY['evt-003', 'evt-007', 'evt-015']
);

Inbox Table Schema

Each inbox gets a table {schema}."{name}_inbox" with this structure: