Webhook Payload Types and Schemas

{
  "type": "StartWebHookPayload",
  "status": "Queued",
  "callId": "660e8400-e29b-41d4-a716-446655440001",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "orgId": "org_123abc",
  "callAdditionalData": {
    "customerId": "cust_789",
    "campaignId": "fall-promo-2024"
  },
  "agentAdditionalData": {
    "department": "sales"
  },
  "endpoint": "+15551234567",
  "sip": {
    "fromUser": "+15551234567",
    "fromDomain": "sip.provider.com",
    "toUser": "agent-line",
    "toDomain": "blackbox.dasha.ai",
    "diversion": [],
    "xHeaders": { "X-Account-Id": "acct-42" },
    "uui": { "raw": "616363742D3432;encoding=hex", "data": "acct-42", "encoding": "hex" },
    "callId": "a84b4c76e66710@sip.provider.com"
  },
  "originalAgentConfig": {
    "primaryLanguage": "en-US",
    "llmConfig": {
      "vendor": "openai",
      "model": "gpt-4.1-mini",
      "prompt": "You are a helpful customer support agent..."
    },
    "ttsConfig": {
      "vendor": "Dasha",
      "voiceId": "default-voice"
    },
    "sttConfig": {
      "vendor": "Auto"
    }
  }
}

{
  "accept": true,
  "overrideAgentConfig": {
    "primaryLanguage": "es-ES",
    "llmConfig": {
      "vendor": "openai",
      "model": "gpt-4.1",
      "prompt": "Eres un agente de soporte al cliente...",
      "options": { "temperature": 0.7 }
    },
    "ttsConfig": {
      "vendor": "ElevenLabs",
      "voiceId": "spanish-voice-id"
    },
    "sttConfig": {
      "vendor": "Auto"
    }
  },
  "additionalData": {
    "customerTier": "premium",
    "preferredLanguage": "es"
  }
}

{
  "accept": false,
  "reasonMessage": "Customer account is suspended"
}

{
  "type": "CompletedWebHookPayload",
  "status": "Completed",
  "callId": "660e8400-e29b-41d4-a716-446655440001",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "orgId": "org_123abc",
  "callAdditionalData": {
    "customerId": "cust_789"
  },
  "agentAdditionalData": {},
  "endpoint": "+15551234567",
  "callType": "OutboundAudio",
  "createdTime": "2024-10-20T14:32:00.000Z",
  "completedTime": "2024-10-20T14:37:45.789Z",
  "durationSeconds": 345.789,
  "inspectorUrl": "https://blackbox.dasha.ai/calls/660e8400-e29b-41d4-a716-446655440001",
  "recordingUrl": "https://storage.blackbox.dasha.ai/recordings/660e8400-e29b-41d4-a716-446655440001.mp3",
  "result": {
    "finishReason": "user_hangup",
    "status": "success",
    "postCallAnalysis": {
      "sentiment": "positive",
      "issueResolved": true,
      "callCategory": "billing_inquiry"
    },
    "transferInformation": []
  },
  "transcription": [
    {
      "speaker": "assistant",
      "name": "Agent",
      "text": "Hello! Thank you for calling. How can I help you today?",
      "startTime": "2024-10-20T14:32:15.000Z",
      "endTime": "2024-10-20T14:32:19.500Z"
    },
    {
      "speaker": "user",
      "name": "Customer",
      "text": "Hi, I have a question about my recent bill.",
      "startTime": "2024-10-20T14:32:20.000Z",
      "endTime": "2024-10-20T14:32:24.000Z"
    },
    {
      "speaker": "assistant",
      "name": "Agent",
      "text": "Of course! I'd be happy to help with your billing question. Could you tell me more about what you're seeing?",
      "startTime": "2024-10-20T14:32:24.500Z",
      "endTime": "2024-10-20T14:32:30.000Z"
    }
  ],
  "toolCalls": [
    {
      "id": "call_8f2d",
      "name": "get_invoice",
      "arguments": { "customerId": "cust_789" },
      "result": { "invoiceId": "inv_1042", "amount": 49.9, "status": "paid" },
      "startTime": "2024-10-20T14:32:31.000Z",
      "endTime": "2024-10-20T14:32:31.420Z"
    }
  ]
}

{
  "type": "CompletedWebHookPayload",
  "status": "Completed",
  "callId": "660e8400-e29b-41d4-a716-446655440003",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "orgId": "org_123abc",
  "callAdditionalData": {
    "customerId": "cust_791"
  },
  "agentAdditionalData": {},
  "endpoint": "+15551234569",
  "callType": "OutboundAudio",
  "createdTime": "2026-09-18T14:32:00.000Z",
  "completedTime": "2026-09-18T14:32:18.000Z",
  "durationSeconds": 18,
  "inspectorUrl": "https://blackbox.dasha.ai/calls/660e8400-e29b-41d4-a716-446655440003",
  "result": {
    "finishReason": "telephony_error",
    "serviceStatus": "failed",
    "status": "Failed",
    "failDetails": "Your telephony provider rejected the call. Provider response: Forbidden.",
    "postCallAnalysis": {},
    "transferInformation": []
  },
  "transcription": [],
  "failure": {
    "stage": "telephony",
    "reason": "forbidden",
    "upstreamOwner": "customer",
    "protocol": "sip",
    "statusCode": 403,
    "retryable": false,
    "message": "Your telephony provider rejected the call.",
    "upstreamMessage": "Forbidden."
  }
}

{
  "type": "FailedWebHookPayload",
  "status": "Failed",
  "callId": "660e8400-e29b-41d4-a716-446655440002",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "orgId": "org_123abc",
  "callAdditionalData": {
    "customerId": "cust_790"
  },
  "agentAdditionalData": {},
  "endpoint": "+15551234568",
  "callType": "OutboundAudio",
  "createdTime": "2024-10-20T14:40:00.000Z",
  "completedTime": "2024-10-20T14:40:30.456Z",
  "errorMessage": "Your configured LLM provider rejected the request. Provider response: Incorrect API key.",
  "failure": {
    "stage": "llm",
    "reason": "authentication",
    "upstreamOwner": "customer",
    "protocol": "http",
    "statusCode": 401,
    "retryable": false,
    "message": "Your configured LLM provider rejected the request.",
    "upstreamMessage": "Incorrect API key."
  },
  "inspectorUrl": "https://blackbox.dasha.ai/calls/660e8400-e29b-41d4-a716-446655440002"
}

{
  "type": "CallDeadLineWebHookPayload",
  "status": "Canceled",
  "callId": "660e8400-e29b-41d4-a716-446655440003",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "orgId": "org_123abc",
  "callAdditionalData": {
    "scheduledFor": "2024-10-20T14:00:00.000Z"
  },
  "agentAdditionalData": {},
  "endpoint": "+15551234569",
  "callType": "OutboundAudio",
  "createdTime": "2024-10-20T13:00:00.000Z",
  "completedTime": "2024-10-20T15:00:00.000Z",
  "reasonMessage": "Call deadline expired before execution"
}

{
  "type": "TransferWebHookPayload",
  "status": "Running",
  "callId": "660e8400-e29b-41d4-a716-446655440004",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "orgId": "org_123abc",
  "callAdditionalData": {
    "customerId": "cust_791",
    "accountTier": "premium"
  },
  "agentAdditionalData": {},
  "endpoint": "+15551234570",
  "transferReason": "Customer requested human agent for billing dispute",
  "transcription": [
    {
      "speaker": "assistant",
      "name": "Agent",
      "text": "I understand you'd like to speak with a billing specialist about your dispute.",
      "startTime": "2024-10-20T14:45:00.000Z",
      "endTime": "2024-10-20T14:45:05.000Z"
    },
    {
      "speaker": "user",
      "name": "Customer",
      "text": "Yes, I need to talk to someone who can actually help me with this refund.",
      "startTime": "2024-10-20T14:45:06.000Z",
      "endTime": "2024-10-20T14:45:10.000Z"
    }
  ]
}

{
  "transferTo": "+15559876543",
  "transferType": "cold"
}

{
  "transferTo": "+15559876543",
  "transferType": "warm",
  "briefing": "Customer Jane Doe needs help with billing dispute. Account: premium tier."
}

{
  "type": "ToolWebHookPayload",
  "status": "Running",
  "callId": "660e8400-e29b-41d4-a716-446655440005",
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "orgId": "org_123abc",
  "callAdditionalData": {
    "customerId": "cust_792"
  },
  "agentAdditionalData": {},
  "endpoint": "+15551234571",
  "toolName": "check_account_balance",
  "arguments": {
    "customerId": "cust_792",
    "accountType": "checking"
  }
}

{
  "balance": 1234.56,
  "currency": "USD",
  "lastTransaction": "2024-10-19T10:15:00Z"
}

const handlers = {
  'StartWebHookPayload': handleStart,
  'CompletedWebHookPayload': handleCompleted,
  'FailedWebHookPayload': handleFailed,
  'CallDeadLineWebHookPayload': handleDeadline,
  'TransferWebHookPayload': handleTransfer,
  'ToolWebHookPayload': handleTool
};

app.post('/webhooks/blackbox', (req, res) => {
  const handler = handlers[req.body.type];
  if (handler) {
    return handler(req.body, res);
  }
  console.warn(`Unknown webhook type: ${req.body.type}`);
  res.status(200).send('OK');
});

// For long-running operations, acknowledge immediately and process asynchronously
app.post('/webhooks/blackbox', async (req, res) => {
  if (req.body.type === 'CompletedWebHookPayload') {
    // Acknowledge immediately
    res.status(200).send('OK');
    // Process asynchronously
    processCompletedCall(req.body).catch(console.error);
    return;
  }
  // For start/transfer/tool webhooks, must respond with data
  // ...
});

app.post('/webhooks/blackbox', (req, res) => {
  const { type } = req.body;

  // Log all received webhooks for debugging
  console.log(`Received webhook: ${type}, callId: ${req.body.callId}`);

  switch (type) {
    case 'StartWebHookPayload':
      return handleStart(req, res);
    case 'CompletedWebHookPayload':
    case 'FailedWebHookPayload':
    case 'CallDeadLineWebHookPayload':
      // Status webhooks don't require response data
      processStatusWebhook(req.body);
      return res.status(200).send('OK');
    case 'TransferWebHookPayload':
      return handleTransfer(req, res);
    case 'ToolWebHookPayload':
      return handleTool(req, res);
    default:
      console.warn(`Unhandled webhook type: ${type}`);
      return res.status(200).send('OK');
  }
});

const express = require('express');
const app = express();
app.use(express.json());

// Start webhook handler - accept/reject calls
async function handleStartWebhook(payload, res) {
  const { callId, callAdditionalData, originalAgentConfig } = payload;

  try {
    // Example: Check if customer is allowed to call
    const customerId = callAdditionalData?.customerId;
    const isAllowed = await checkCustomerStatus(customerId);

    if (!isAllowed) {
      return res.json({
        accept: false,
        reasonMessage: 'Customer account is not active'
      });
    }

    // Example: Override config based on customer tier
    const customerTier = await getCustomerTier(customerId);
    if (customerTier === 'premium') {
      return res.json({
        accept: true,
        overrideAgentConfig: {
          ...originalAgentConfig,
          llmConfig: {
            ...originalAgentConfig.llmConfig,
            model: 'gpt-4.1' // Upgrade to better model for premium
          }
        },
        additionalData: {
          customerTier: 'premium'
        }
      });
    }

    // Accept with default config
    return res.json({ accept: true });

  } catch (error) {
    console.error('Start webhook error:', error);
    // On error, accept with default config
    return res.json({ accept: true });
  }
}

// Completed webhook handler - process results
async function handleCompletedWebhook(payload) {
  const {
    callId,
    transcription,
    result,
    durationSeconds,
    callAdditionalData
  } = payload;

  // Store call data
  await storeCallRecord({
    callId,
    customerId: callAdditionalData?.customerId,
    duration: durationSeconds,
    transcript: transcription,
    postCallAnalysis: result.postCallAnalysis,
    finishReason: result.finishReason
  });

  // Trigger follow-up actions based on analysis
  if (result.postCallAnalysis?.issueResolved === false) {
    await createFollowUpTask(callId, callAdditionalData?.customerId);
  }
}

// Failed webhook handler - handle errors
async function handleFailedWebhook(payload) {
  const { callId, errorMessage, callAdditionalData } = payload;

  await logCallFailure({
    callId,
    customerId: callAdditionalData?.customerId,
    error: errorMessage
  });

  // Alert on repeated failures
  const recentFailures = await getRecentFailureCount(
    callAdditionalData?.customerId,
    '1h'
  );
  if (recentFailures > 3) {
    await alertOperations('High failure rate for customer');
  }
}

// Transfer webhook handler - route calls
async function handleTransferWebhook(payload, res) {
  const { callAdditionalData, transferReason } = payload;

  try {
    // Route based on customer tier or transfer reason
    const customerId = callAdditionalData?.customerId;
    const accountTier = callAdditionalData?.accountTier;

    if (accountTier === 'premium') {
      // Premium customers get warm transfer to dedicated rep
      const assignedRep = await getAssignedRep(customerId);
      return res.json({
        transferTo: assignedRep.phone,
        transferType: 'warm',
        briefing: `Premium customer ${customerId}. Reason: ${transferReason}`
      });
    }

    // Standard customers get cold transfer to queue
    return res.json({
      transferTo: '+1-555-0100',
      transferType: 'cold'
    });

  } catch (error) {
    console.error('Transfer webhook error:', error);
    // Fallback to default support line
    return res.json({
      transferTo: '+1-555-0100',
      transferType: 'cold'
    });
  }
}

// Tool webhook handler - execute functions
async function handleToolWebhook(payload, res) {
  const { toolName, arguments: args, callAdditionalData } = payload;

  try {
    switch (toolName) {
      case 'check_account_balance':
        const balance = await getAccountBalance(
          args.customerId,
          args.accountType
        );
        return res.json(balance);

      case 'schedule_callback':
        const scheduled = await scheduleCallback(
          callAdditionalData?.customerId,
          args.preferredTime
        );
        return res.json({ success: true, scheduledTime: scheduled });

      case 'process_refund':
        const refund = await processRefund(
          args.orderId,
          args.amount
        );
        return res.json(refund);

      default:
        return res.json({ error: `Unknown tool: ${toolName}` });
    }
  } catch (error) {
    console.error(`Tool ${toolName} error:`, error);
    return res.json({ error: error.message });
  }
}

// Main webhook endpoint
app.post('/webhooks/blackbox', async (req, res) => {
  const payload = req.body;

  console.log(`Webhook received: ${payload.type}, callId: ${payload.callId}`);

  switch (payload.type) {
    case 'StartWebHookPayload':
      return handleStartWebhook(payload, res);

    case 'CompletedWebHookPayload':
      await handleCompletedWebhook(payload);
      return res.status(200).send('OK');

    case 'FailedWebHookPayload':
      await handleFailedWebhook(payload);
      return res.status(200).send('OK');

    case 'CallDeadLineWebHookPayload':
      console.log(`Call ${payload.callId} canceled: ${payload.reasonMessage}`);
      return res.status(200).send('OK');

    case 'TransferWebHookPayload':
      return handleTransferWebhook(payload, res);

    case 'ToolWebHookPayload':
      return handleToolWebhook(payload, res);

    default:
      console.warn(`Unknown webhook type: ${payload.type}`);
      return res.status(200).send('OK');
  }
});

// Health check
app.get('/health', (req, res) => res.status(200).send('OK'));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook server running on port ${PORT}`);
});