Skip to main content
POST
/
webhooks
Create Webhook
curl --request POST \
  --url https://api.example.com/webhooks \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    {}
  ],
  "name": "<string>",
  "description": "<string>",
  "companyId": "<string>",
  "headers": [
    {}
  ]
}
'
{
  "id": "<string>",
  "signingSecret": "<string>",
  "url": "<string>",
  "events": [
    {}
  ],
  "isActive": true
}
Creates a new webhook configuration for receiving event notifications.

​
Overview

Create a webhook to receive real-time HTTP notifications when events occur in your InstaView account. The signing secret is returned only once during creation—store it securely.

​
Authentication

​
Authorization
string
required
Bearer token with write:webhooks scope

​
Request Body

​
url
string
required
The HTTPS endpoint URL to receive webhook notifications. Maximum 2048 characters.
​
events
array
required
Array of event type strings to subscribe to:
  • "ANALYSIS_COMPLETED" - Analysis finished successfully
  • "ANALYSIS_FAILED" - Analysis processing failed
  • "PING" - Test event for connectivity
  • "INTERVIEW_COMPLETED" - Interview finished with analysis
  • "INTERVIEW_FAILED" - Technical failure during interview
  • "INTERVIEW_STARTED" - Interview session began
  • "SOURCING_COMPLETED" - Sourcing run finished with scored candidates
  • "SOURCING_FAILED" - Sourcing run terminated with an error
  • "ENRICH_COMPLETED" - Enrichment run completed
  • "ENRICH_FAILED" - Enrichment run terminated with an error
​
name
string
Human-readable name for the webhook. Maximum 255 characters.
​
description
string
Description of what this webhook is used for.
​
companyId
string
Company ID to associate this webhook with. If omitted, webhook will receive events for all companies accessible by the API key. Useful for ATS integrations managing multiple companies with different subdomains.
​
headers
array
Custom headers to include in webhook requests. Maximum 50 headers.Each header object:
  • name (string, required): Header name (1-255 characters)
  • value (string, required): Header value (1-4096 characters)

​
Response

Returns the created webhook configuration with the signing secret.
The signingSecret is only returned once during creation. Store it securely immediately. If you lose it, you must delete and recreate the webhook.
​
id
string
Unique identifier for the webhook
​
signingSecret
string
HMAC signing secret for verifying webhook signatures (hex-encoded, 64 characters)
​
url
string
The endpoint URL
​
events
array
Array of subscribed event type labels
​
isActive
boolean
Whether the webhook is active (always true for new webhooks)

​
Example Request

curl -X POST https://api.instaview.sk/webhooks \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/instaview",
    "name": "Production Webhook",
    "description": "Receives interview completion notifications",
    "events": ["INTERVIEW_COMPLETED", "ANALYSIS_COMPLETED"],
    "headers": [
      { "name": "Authorization", "value": "Bearer your-internal-token" }
    ]
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "apiKeyId": "api-key-uuid",
    "companyId": "company-uuid",
    "url": "https://api.example.com/webhooks/instaview",
    "name": "Production Webhook",
    "description": "Receives interview completion notifications",
    "headers": [
      { "name": "Authorization", "isMasked": true }
    ],
    "events": ["interview.completed", "analysis.completed"],
    "isActive": true,
    "maxRetries": 3,
    "timeoutMs": 30000,
    "consecutiveFailures": 0,
    "circuitOpenedAt": null,
    "signingSecret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "url must be a valid URL"
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Required scope write:webhooks not found"
  }
}

​
Best Practices

  1. Store the signing secret immediately - It’s only returned once
  2. Include the ping event for testing - You can remove it later
  3. Use HTTPS endpoints - HTTP is only allowed for localhost
  4. Add authentication headers - Protect your webhook endpoint

Webhooks Guide

Learn about signature verification and payloads

Test Webhook

Test your webhook endpoint