Webhooks

{ "vocabulary": "NEUTRAL" }

{
  "event": "conversation.completed",
  "timestamp": "2024-01-20T14:30:00.000Z",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    // Event-specific data
  }
}

{
  "event": "conversation.completed",
  "timestamp": "2024-01-20T14:30:00.000Z",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "conversationId": "conversation-uuid",
    "interviewId": "conversation-uuid",
    "callAttemptId": "call-attempt-uuid",
    "contactId": "contact-uuid",
    "candidateId": "contact-uuid",
    "runId": null,
    "jobId": "job-uuid",
    "status": "COMPLETED"
  }
}

{
  "event": "conversation.cancelled",
  "timestamp": "2024-01-20T14:30:00.000Z",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "conversationId": "conversation-uuid",
    "interviewId": "conversation-uuid",
    "contactId": "contact-uuid",
    "candidateId": "contact-uuid",
    "runId": null,
    "jobId": "job-uuid",
    "status": "CANCELLED",
    "reason": "MAX_ATTEMPTS_EXCEEDED",
    "reasonDetail": "Retry limit of 5 reached (last failure: customer-busy)",
    "lastCallAttemptId": "call-attempt-uuid-5",
    "attemptsMade": 5,
    "cancelledBy": "SYSTEM"
  }
}

# Busy on the first try, answered on the second
conversation.started → conversation.rescheduled (BUSY) → conversation.started
                     → conversation.completed → analysis.completed

# Never reached
conversation.started → conversation.rescheduled (NO_ANSWER) → conversation.started
                     → conversation.rescheduled (NO_ANSWER) → … → conversation.cancelled (MAX_ATTEMPTS_EXCEEDED)

{
  "event": "conversation.failed",
  "timestamp": "2024-01-20T14:30:00.000Z",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "conversationId": "conversation-uuid",
    "interviewId": "conversation-uuid",
    "callAttemptId": "call-attempt-uuid",
    "contactId": "contact-uuid",
    "candidateId": "contact-uuid",
    "runId": null,
    "jobId": "job-uuid",
    "status": "FAILED",
    "errorMessage": "Connection timeout during call"
  }
}

{
  "event": "ping",
  "timestamp": "2024-01-20T14:30:00.000Z",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "message": "Test ping from InstaView webhook system"
  }
}

// Webhook for Company A
await createWebhook({
  url: "https://company-a.yourats.com/webhooks/instaview",
  companyId: "company-a-uuid",
  events: ["CONVERSATION_COMPLETED", "ANALYSIS_COMPLETED"],
});

// Webhook for Company B
await createWebhook({
  url: "https://company-b.yourats.com/webhooks/instaview",
  companyId: "company-b-uuid",
  events: ["CONVERSATION_COMPLETED", "ANALYSIS_COMPLETED"],
});

// Global webhook (receives all events)
await createWebhook({
  url: "https://admin.yourats.com/webhooks/instaview",
  // No companyId - receives events for all companies
  events: ["CONVERSATION_COMPLETED", "ANALYSIS_COMPLETED"],
});

// List all webhooks (includes both company-specific and global webhooks)
const allWebhooks = await fetch("/webhooks", { headers });

// List webhooks for a specific company (excludes global webhooks)
// Only returns webhooks that have the specified companyId
const companyWebhooks = await fetch("/webhooks?companyId=company-uuid", {
  headers,
});

const response = await fetch("https://api.instaview.sk/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://api.yourcompany.com/webhooks/instaview",
    name: "Production Webhook",
    description: "Receives conversation completion notifications",
    events: ["CONVERSATION_COMPLETED", "ANALYSIS_COMPLETED"],
    companyId: "company-uuid", // Optional: Associate with specific company
    headers: [{ name: "Authorization", value: "Bearer your-internal-token" }],
  }),
});

const data = await response.json();

// IMPORTANT: Store this secret securely - it's only shown once!
console.log("Signing secret:", data.signingSecret);

// List all webhooks (includes both company-specific and global webhooks)
const response = await fetch("https://api.instaview.sk/webhooks", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

// Filter by company ID (returns only company-specific webhooks, excludes global ones)
const responseFiltered = await fetch(
  "https://api.instaview.sk/webhooks?companyId=company-uuid",
  {
    headers: { Authorization: `Bearer ${apiKey}` },
  },
);

const data = await response.json();
console.log(`Found ${data.total} webhooks`);

for (const webhook of data.data) {
  console.log(`${webhook.name}: ${webhook.url}`);
  console.log(`  Company: ${webhook.companyId || "All companies"}`);
  console.log(`  Events: ${webhook.events.join(", ")}`); // These will be labels like "analysis.completed"
  console.log(`  Active: ${webhook.isActive}`);
  console.log(`  Failures: ${webhook.consecutiveFailures}`);
}

await fetch(`https://api.instaview.sk/webhooks/${webhookId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://api.yourcompany.com/webhooks/instaview-v2",
    events: [
      "CONVERSATION_COMPLETED",
      "CONVERSATION_FAILED",
      "ANALYSIS_COMPLETED",
      "ANALYSIS_FAILED",
    ],
    isActive: true,
  }),
});

await fetch(`https://api.instaview.sk/webhooks/${webhookId}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${apiKey}` },
});

const response = await fetch(
  `https://api.instaview.sk/webhooks/${webhookId}/test`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}` },
  },
);

const data = await response.json();

if (data.success) {
  console.log("Webhook test successful!");
  console.log(`Response time: ${data.durationMs}ms`);
} else {
  console.error("Webhook test failed:", data.message);
}

// Create a test conversation that completes immediately
const response = await fetch("https://api.instaview.sk/conversations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact-uuid",
    agentId: "agent-uuid",
    isTest: true, // Completes immediately, bills nothing
  }),
  // Without a deadline this request never settles if the API stops answering.
  signal: AbortSignal.timeout(10_000),
});

// Nothing was created unless the API said so — a 4xx body parses just as happily as a
// conversation would, and waiting for webhooks that will never arrive is the failure mode.
if (!response.ok) {
  const error = await response.json().catch(() => ({}));
  throw new Error(
    `Creating the test conversation failed: ${response.status} ${error.message ?? response.statusText}`,
  );
}

const testConversation = await response.json();

// Now that it exists, it will trigger:
// 1. conversation.completed webhook
// 2. analysis.completed webhook
// Both events will be sent to your webhook endpoint

await fetch(`https://api.instaview.sk/webhooks/${webhookId}/reset-circuit`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
});

{
  "url": "https://api.yourcompany.com/webhooks/instaview",
  "headers": [
    { "name": "Authorization", "value": "Bearer your-internal-token" },
    { "name": "X-Custom-Header", "value": "custom-value" }
  ],
  "events": ["CONVERSATION_COMPLETED", "ANALYSIS_COMPLETED"]
}