Skip to main content
POST
Create Webhook
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

string
required
Bearer token with write:webhooks scope

Request Body

string
required
The HTTPS endpoint URL to receive webhook notifications. Maximum 2048 characters.
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
  • "CONVERSATION_COMPLETED" - The call finished and analysis is available
  • "CONVERSATION_FAILED" - A technical failure prevented the call
  • "CONVERSATION_STARTED" - A call attempt began
  • "CONVERSATION_RESCHEDULED" - A follow-up call attempt has been scheduled
  • "CONVERSATION_CANCELLED" - The conversation ended without completing
  • "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
The five conversation events also accept their legacy spellings — "INTERVIEW_COMPLETED" and siblings — which register exactly the same subscription. See Event name vocabulary.
string
Human-readable name for the webhook. Maximum 255 characters.
string
Description of what this webhook is used for.
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.
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.
string
Unique identifier for the webhook
string
HMAC signing secret for verifying webhook signatures (hex-encoded, 64 characters)
string
The endpoint URL
array
Array of subscribed event type labels
boolean
Whether the webhook is active (always true for new webhooks)

Example Request

Example Response

Error Responses

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