Integrations

Integrations in TraceMem are the transport layer for approval delivery. They handle the technical details of delivering approval requests to humans via different communication channels.

Key Principle: Integrations are transport mechanisms. They deliver approval requests but do not define approval logic or requirements.

What Integrations Are

An Integration is:

• A configured connection to an external communication system
• A transport mechanism for approval requests and responses
• A technical delivery channel (Slack, Email, Webhook)
• A credential and configuration store
• A delivery reliability mechanism

It answers:

"How are approval requests delivered to humans?"

What Integrations Are Not

An Integration is not:

• An approval route (routes define where to send, integrations handle delivery)
• A policy (policies define when approvals are needed)
• An approval authority (integrations deliver, they don't decide)
• A workflow engine
• A replacement for business logic

Integrations provide the "how" of delivery. Approval Routes provide the "where" and "what".

Integration Types

TraceMem supports different integration types based on the communication channel:

Slack Integration

Delivers approval requests via Slack messages with interactive buttons.

Capabilities:

• Interactive approval buttons (Approve/Reject)
• Channel routing
• Real-time notifications
• Approver identity capture from Slack
• Message updates to reflect final outcome

Configuration:

• Workspace ID
• Bot token
• Signing secret
• Default approval channel (optional)

Email Integration

Delivers approval requests via email with magic-link approval.

Capabilities:

• HTML email templates
• Signed, time-bound approval links
• Confirmation emails after resolution
• Reply-to handling

Configuration:

• Email provider (SMTP, SES, etc.)
• From name and email
• Reply-to address
• TLS requirements

Webhook Integration

Delivers approval requests via HTTP webhooks to custom endpoints.

Capabilities:

• Outbound approval request webhooks
• Inbound approval callback handling
• HMAC or signature verification
• Retry logic and timeout handling
• Event filtering (approval.requested, approval.resolved)

Configuration:

• Webhook URL
• Secret for signature verification
• Timeout settings
• Maximum retry attempts
• Event subscriptions

Integration Lifecycle

1. Creation

Integrations are created by administrators via:

• The Admin Dashboard
• The Admin API

Agents cannot create or modify Integrations.

2. Configuration

Each integration type requires specific configuration:

• Slack: Bot token, signing secret, workspace ID
• Email: SMTP/SES credentials, from address, reply-to
• Webhook: URL, secret, timeout, retry settings

Credentials are encrypted at rest and never returned in API responses.

3. Testing

Integrations can be tested to verify:

• Connectivity to the external system
• Credential validity
• Delivery capability
• End-to-end functionality

4. Status Monitoring

Integrations have status indicators:

• configured - Integration is set up and ready
• enabled - Integration is active and delivering
• disabled - Integration is temporarily disabled
• error - Integration has delivery failures

How Integrations Work

Delivery Flow

Approval Request Created
    ↓
Approval Route Selected
    ↓
Integration Identified (from route)
    ↓
Integration Delivers Request
    ↓
Human Responds (via integration)
    ↓
Response Recorded in TraceMem
    ↓
Decision State Updated

Asynchronous Delivery

Approval requests are delivered asynchronously by background workers:

1. Agent requests approval
2. Approval request queued
3. Worker picks up request
4. Worker uses integration to deliver
5. Human responds via integration
6. Response recorded in TraceMem
7. Decision state updated

Important: Even if delivery fails, the approval request is recorded in the decision trace.

Integration Security

Credential Storage

Integration credentials are:

• Encrypted at rest using AES-256
• Never returned in API responses (only { "stored": true })
• Stored separately from configuration
• Rotatable via API

Signature Verification

For webhook integrations:

• Outbound requests include HMAC signatures
• Inbound callbacks must include valid signatures
• Secrets are never exposed in logs or errors

Access Control

Integrations are:

• Tenant-scoped (isolated per tenant)
• Only accessible via Admin API (JWT authentication)
• Never directly accessible to agents
• Used indirectly through Approval Routes

Relationship to Other Concepts

Integrations → Approval Routes

Approval Routes reference Integrations to determine how to deliver approval requests:

• Approval Routes define which integration to use and where to send
• Integrations handle the technical delivery

A single integration can be used by multiple approval routes.

Integrations → Approvals

Integrations deliver approval requests and receive responses:

• Approval requests are delivered via integrations
• Human responses come back through integrations
• Integrations are transport only; TraceMem is the source of truth

Integrations → Decision Traces

Integration delivery is recorded in decision traces:

• Which integration was used
• When delivery was attempted
• Whether delivery succeeded or failed
• How the human responded

Where Integrations Sit in the Flow

Policy Evaluation
    ↓ (requires_exception)
Approval Route Selected
    ↓
Integration Identified
    ↓
Integration Delivers Request
    ↓
Human Responds
    ↓
Response Recorded
    ↓
Decision Trace Updated

Key points:

• Agents never see integrations directly
• Approval Routes abstract integrations from policies
• Integrations provide the transport layer
• TraceMem records all delivery attempts and responses

Best Practices

1. Test integrations after setup - Verify end-to-end delivery
2. Monitor integration status - Check for delivery failures
3. Rotate credentials regularly - Update tokens and secrets periodically
4. Use separate integrations for environments - Dev, staging, production
5. Configure retries appropriately - Balance reliability with timeout handling
6. Secure webhook secrets - Never expose secrets in logs or error messages
7. Monitor delivery success rates - Track integration health

Mental Model

Integrations are the postal service.
Approval Routes are the address labels.
Policies are the reason for sending.
The postal service doesn't care what's in the envelope or why it's being sent.
It just delivers it to the address on the label.
The recipient responds, and the postal service brings the response back.
TraceMem is the sender and receiver, keeping records of everything.