How valext Works

​

valext Protocol

Note: The extension system is currently under development. The information below is a preview of what will be available.

​

Event-Driven Architecture

​

Event Types

• invoice.created - New invoice generated
• invoice.paid - Invoice payment received
• outcome.completed - Business outcome achieved
• subscription.created - New subscription
• subscription.updated - Subscription changed
• payment.successful - Payment processed

​

Event Payload

• Event Type: What happened
• Timestamp: When it happened
• Data: Event-specific data
• Metadata: Additional context

​

Extension Lifecycle

​

1. Registration

• Provide extension metadata
• Subscribe to event types
• Configure authentication

​

2. Event Reception

• Valmi Value sends event to extension
• Extension receives event via webhook or polling
• Extension validates event authenticity

​

3. Processing

• Transforms data to external system format
• Calls external system API
• Handles errors and retries

​

4. Response

• Success: Event processed successfully
• Failure: Error occurred (with retry)
• Status: Processing status updates

​

Metadata Contracts

​

Invoice Metadata

{
  "invoice_id": "inv_abc123",
  "account_id": "account_xyz789",
  "amount": 1000.00,
  "currency": "USD",
  "line_items": [...],
  "due_date": "2024-02-15"
}

​

Payment Metadata

{
  "payment_id": "pay_abc123",
  "invoice_id": "inv_xyz789",
  "amount": 1000.00,
  "currency": "USD",
  "payment_method": "stripe",
  "transaction_id": "txn_123"
}

​

Mapping to Upstream Systems

​

Stripe Mapping

def map_to_stripe(invoice):
    return {
        "amount": int(invoice.amount * 100),  # Convert to cents
        "currency": invoice.currency.lower(),
        "customer": invoice.account.stripe_customer_id,
        "metadata": {
            "valmi_invoice_id": invoice.id
        }
    }

​

QuickBooks Mapping

def map_to_quickbooks(invoice):
    return {
        "Line": [
            {
                "Amount": invoice.amount,
                "DetailType": "SalesItemLineDetail",
                "SalesItemLineDetail": {
                    "ItemRef": {"value": "1"}
                }
            }
        ],
        "CustomerRef": {"value": invoice.account.quickbooks_id}
    }

​

Error Handling

• Retries: Automatic retry with exponential backoff
• Dead Letter Queue: Failed events stored for manual review
• Notifications: Alert on persistent failures
• Logging: Comprehensive error logging

​

Extension Configuration

• API Keys: External system credentials
• Mapping Rules: How to transform data
• Retry Policies: How to handle failures
• Filters: Which events to process