Payment Schema
The payment schema contains 1 model that manages webhook endpoint configurations for dispatching payment and transaction events to external systems.
Source: packages/core/src/models/schemas/payment/
WebhookConfig
Webhook endpoint registration with event type filtering, custom headers, and retry configuration.
Columns
| Column | Type | Constraints | Description |
|---|---|---|---|
id | text | PK | Snowflake ID |
name | text | NOT NULL | Webhook name |
url | text | NOT NULL | Webhook endpoint URL |
event_types | text[] | NOT NULL | Array of event types to listen for |
status | text | NOT NULL, DEFAULT ACTIVATED, indexed | Webhook status |
headers | jsonb | DEFAULT {} | Custom HTTP headers (e.g., auth tokens) |
metadata | jsonb | DEFAULT { timeoutMs: 30000, maxRetries: 3 } | Retry and timeout configuration |
created_at | timestamptz | Creation timestamp | |
modified_at | timestamptz | Last modification timestamp |
Note: WebhookConfig uses generateIdColumnDefs({ id: { dataType: 'string' } }) + generateTzColumnDefs() directly (no deletedAt or soft-delete support).
Status Values
| Status | Value | Description |
|---|---|---|
| ACTIVATED | 201_ACTIVATED | Webhook is active and will receive events |
| DEACTIVATED | 401_DEACTIVATED | Webhook is paused, events will not be dispatched |
| ARCHIVED | 405_ARCHIVED | Webhook is archived and permanently disabled |
Statuses are defined in WebhookConfigStatuses (from packages/core/src/common/constants.ts).
Metadata Schema
The metadata field is validated by a Zod schema:
export const WebhookConfigMetadataSchema = z.object({
timeoutMs: z.number().int().min(1000).max(300_000).default(30_000),
maxRetries: z.number().int().min(0).max(10).default(3),
});| Field | Type | Range | Default | Description |
|---|---|---|---|---|
timeoutMs | integer | 1,000 -- 300,000 | 30,000 | HTTP request timeout in milliseconds |
maxRetries | integer | 0 -- 10 | 3 | Maximum retry attempts on failure |
Event Types
The event_types array filters which events trigger this webhook. Common MQ-Pay event types include:
| Event | Description |
|---|---|
mq-pay:transaction.created | New payment transaction created |
mq-pay:transaction.settled | Transaction fully settled |
mq-pay:transaction.cancelled | Transaction cancelled |
mq-pay:attempt.created | Payment attempt initiated |
mq-pay:attempt.sent | Payment attempt sent to provider |
mq-pay:attempt.success | Payment attempt succeeded |
mq-pay:attempt.failed | Payment attempt failed |
mq-pay:attempt.expired | Payment attempt expired |
mq-pay:attempt.cancelled | Payment attempt cancelled |
mq-pay:refund.success | Refund succeeded |
mq-pay:refund.failed | Refund failed |
Webhook Dispatch
The WebhookDispatcherService (in @nx/payment) handles event dispatch:
- Fire-and-forget delivery with exponential backoff retry
- Custom headers from the
headersfield are included in each request - Timeout and retry limits are read from the
metadatafield - Only ACTIVATED webhooks receive events
Entity Diagram
Related Documentation
- Database Overview -- Schema summary, common columns, shared types
- Entity Relationship Diagram -- Comprehensive ERD for all 55 models
- Public Schema -- 30 models in the public schema
- Pricing Schema -- 7 pricing models
- Allocation Schema -- 4 allocation models
- Sale Schema -- 2 sale order models
- Inventory Schema -- 8 inventory models
- Finance Schema -- 3 finance models
- Migrations -- DDL migrations and seed data framework
- Payment Package -- Payment orchestration, webhook config, and MQ-Pay integration
- MQ-Pay Integration -- Multi-provider payment system