core/docs/oauth-integration-webhook-implementation.md

OAuth Integration Webhook Implementation

This document describes the implementation of webhook notifications for OAuth applications when users connect new integrations, following the existing trigger-based architecture.

Architecture

The implementation follows the established pattern used in the Echo system:

• Integration Creation: Happens in integration-run trigger
• Webhook Delivery: Uses dedicated trigger task for asynchronous processing
• Error Handling: Non-blocking - webhook failures don't affect integration creation

Implementation Components

1. OAuth Integration Webhook Delivery Task

File: apps/webapp/app/trigger/webhooks/oauth-integration-webhook-delivery.ts

This is a dedicated trigger task that handles webhook delivery to OAuth applications:

export const oauthIntegrationWebhookTask = task({
  id: "oauth-integration-webhook-delivery",
  queue: oauthIntegrationWebhookQueue,
  run: async (payload: OAuthIntegrationWebhookPayload) => {
    // Implementation
  },
});

Key Features:

• Finds OAuth clients with integration scope for the user
• Sends webhook notifications with integration details
• Includes HMAC signature verification
• Provides detailed delivery status tracking
• Non-blocking error handling

2. Integration into Integration-Run Trigger

File: apps/webapp/app/trigger/integrations/integration-run.ts

Modified the handleAccountMessage function to trigger webhook notifications:

async function handleAccountMessage(...) {
  // Create integration account
  const integrationAccount = await createIntegrationAccount({...});

  // Trigger OAuth integration webhook notifications
  try {
    await triggerOAuthIntegrationWebhook(integrationAccount.id, userId);
  } catch (error) {
    // Log error but don't fail integration creation
  }

  return integrationAccount;
}

Integration Points:

• Triggered after successful integration account creation
• Works for all integration types (OAuth, API key, MCP)
• Maintains existing integration creation flow

Webhook Flow

1. Integration Connection

When a user connects a new integration:

1. Integration runs through IntegrationEventType.SETUP
2. CLI returns "account" message
3. handleAccountMessage creates integration account
4. triggerOAuthIntegrationWebhook is called
5. Webhook delivery task is queued

2. Webhook Delivery

The webhook delivery task:

1. Queries OAuth clients with:
   • integration scope in allowedScopes
   • Active OAuthIntegrationGrant for the user
   • Configured webhookUrl
2. Sends HTTP POST to each webhook URL
3. Logs delivery results

3. Webhook Payload

{
  "event": "integration.connected",
  "user_id": "user_uuid",
  "integration": {
    "id": "integration_account_uuid",
    "provider": "linear",
    "account_id": "external_account_id",
    "mcp_endpoint": "mcp://core.ai/linear/external_account_id",
    "name": "Linear",
    "icon": "https://example.com/linear-icon.png"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Security Features

HMAC Signature

If OAuth client has webhookSecret configured:

const signature = crypto
  .createHmac("sha256", client.webhookSecret)
  .update(payloadString)
  .digest("hex");
headers["X-Webhook-Secret"] = signature;

Headers

• Content-Type: application/json
• User-Agent: Echo-OAuth-Webhooks/1.0
• X-Webhook-Delivery: ${deliveryId}
• X-Webhook-Event: integration.connected
• X-Webhook-Secret: ${signature} (if secret configured)

Error Handling

Non-Blocking Design

• Webhook delivery failures do NOT affect integration creation
• Errors are logged but don't throw exceptions
• Integration process continues normally

Retry Strategy

Currently, the system uses Trigger.dev's built-in retry mechanism:

• Failed webhook deliveries will be retried automatically
• Exponential backoff for temporary failures
• Dead letter queue for permanent failures

Logging

Comprehensive logging includes:

• Integration account details
• OAuth client information
• HTTP response status and body
• Error messages and stack traces
• Delivery success/failure counts

Database Requirements

The implementation requires these existing database relationships:

OAuthClient

• webhookUrl: Target URL for notifications
• webhookSecret: Optional HMAC secret
• allowedScopes: Must include "integration"

OAuthIntegrationGrant

• Links OAuth clients to users
• isActive: Must be true for notifications
• userId: Target user for the integration

IntegrationAccount

• Created during integration setup
• Includes integrationDefinition relationship
• Contains provider-specific configuration

Testing

To test the webhook delivery:

1. Create OAuth Client with integration scope:

UPDATE "OAuthClient"
SET "allowedScopes" = 'profile,email,openid,integration',
    "webhookUrl" = 'https://your-webhook-endpoint.com/webhooks'
WHERE "clientId" = 'your-client-id';

2. Grant Integration Access through OAuth flow with integration scope

3. Connect Integration (Linear, Slack, etc.) - webhooks will be triggered automatically

4. Monitor Logs for delivery status and any errors

Advantages of This Approach

1. Follows Existing Patterns: Uses the same trigger-based architecture as other webhook systems
2. Scalable: Leverages Trigger.dev's queue system for handling high volumes
3. Reliable: Built-in retry and error handling
4. Non-Blocking: Integration creation is never blocked by webhook issues
5. Comprehensive: Works with all integration types and OAuth flows
6. Secure: Includes HMAC signature verification and proper headers
7. Observable: Detailed logging for monitoring and debugging

This implementation ensures that OAuth applications are immediately notified when users connect new integrations, while maintaining the reliability and scalability of the existing system architecture.