Skip to main content

Overview

Webhooks enable your application to receive real-time notifications when events occur in InstaView. Instead of polling the API, webhooks push data to your endpoint immediately when interviews complete, analyses finish, or other events happen.

How Webhooks Work

1

Configure Endpoint

Register your webhook URL and specify which events to receive
2

Event Occurs

An interview completes, analysis finishes, or other tracked event happens
3

Receive Notification

InstaView sends an HTTP POST request to your endpoint with event details
4

Process & Respond

Your server processes the event and returns a 2xx status code

Event Types

InstaView supports the following webhook event types:

Event Type Strings

There is a distinction between the strings used to register a webhook and the strings sent in the webhook payload:

Registration (Screaming Snake Case)

When creating or updating webhooks, use these uppercase strings in the events array:
  • "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

Payload (Dot Notation)

The event field in the JSON payload you receive will use lowercase dot notation (e.g., "analysis.completed").

Payload Structure

All webhook payloads follow this structure:

Interview Events Payload

Analysis Events Payload

Failed Event Payloads

Failed events include an error message:

Ping Event Payload

Most webhook payloads contain minimal data (IDs and status), but the analysis.completed event includes the full analysis results and the analysisPdfBase64 Base64-encoded PDF report (when generation succeeds). For other details like transcripts, use the Interview API to fetch the complete resource.

Per-Company Webhooks

For ATS integrations managing multiple companies, you can register webhooks per company by specifying the companyId parameter when creating a webhook. This enables:
  • Company-specific endpoints: Each company can have its own webhook URL (e.g., different subdomains)
  • Selective event delivery: Webhooks with companyId only receive events for that specific company
  • Global webhooks: Webhooks without companyId receive events for all companies accessible by the API key

Example: Per-Company Setup

Filtering by Company

When listing webhooks, you can filter by company:
Note: When filtering by companyId, only company-specific webhooks are returned. Global webhooks (those without a companyId) are excluded from filtered results. To see all webhooks including global ones, omit the companyId parameter.

Required Scopes

Security

Signature Verification

Every webhook request includes an HMAC-SHA256 signature in the X-Webhook-Signature header. Always verify this signature to ensure requests are from InstaView. The signature format is: sha256=<hex-encoded-signature>

Request Headers

Every webhook request includes these headers: Plus any custom headers you configured when creating the webhook.

Secret Management

Store your signing secret securely! The signing secret is only returned once when you create a webhook configuration. If lost, you must delete and recreate the webhook to get a new secret.
Best practices for secret management:
  • Store secrets in environment variables or a secrets manager
  • Never commit secrets to version control
  • Rotate secrets periodically by creating new webhooks
  • Use different secrets for development and production

Retry Logic

If your endpoint fails to respond with a 2xx status code, InstaView automatically retries delivery with exponential backoff:
1

Immediate Attempt

First delivery attempt immediately when event occurs
2

Retry 1

After a short delay if first attempt fails
3

Retry 2

After a longer delay if second attempt fails
4

Retry 3

Final attempt with maximum delay
After all retries are exhausted, the delivery is marked as failed.

Circuit Breaker

To protect both your system and ours, InstaView implements a circuit breaker pattern:
  • If a webhook consistently fails, it will be automatically disabled
  • You can monitor the consecutiveFailures count in the webhook configuration
  • When disabled, the circuitOpenedAt timestamp indicates when the circuit opened
  • Use the Reset Circuit Breaker endpoint to re-enable the webhook after fixing issues

Endpoint Requirements

Your webhook endpoint must:
Return a 2xx response within 30 seconds. For long-running tasks, acknowledge receipt immediately and process asynchronously.
Handle duplicate deliveries gracefully using the deliveryId:
Production webhook URLs must use HTTPS. HTTP is only allowed for localhost during development.
Any 2xx status code indicates successful receipt. Retry behavior depends on the status code:

Managing Webhooks

Create a Webhook

Per-Company Webhooks: For ATS integrations managing multiple companies, you can specify companyId when creating a webhook. This allows you to register separate webhooks per company (e.g., different subdomains). If omitted, the webhook will receive events for all companies accessible by the API key (global webhook).

List Webhooks

Update a Webhook

Delete a Webhook

Test a Webhook

Send a test ping to verify connectivity:
To test a webhook using the test endpoint above, it must be subscribed to the ping event.

Test Interview Events with Test Interviews

For more comprehensive testing of interview-related webhook events (interview.completed, analysis.completed), you can create test interviews using the isTest flag:
Test interviews are useful for:
  • Testing your webhook handler’s processing logic for interview completion
  • Verifying that analysis data is correctly parsed and stored
  • End-to-end testing of your integration without waiting for real interviews
  • Development and debugging without consuming billing minutes
See the Create Interview documentation for more details on test mode.

Reset Circuit Breaker

If your webhook was disabled due to consecutive failures:

Custom Headers

You can configure custom headers to authenticate with your endpoint:
Security: Sensitive headers (Authorization, X-API-Key, X-Secret, API-Key) are automatically encrypted at rest. When listing webhooks, these header values are masked for security.

Best Practices

Verify Signatures

Always verify the X-Webhook-Signature header to ensure requests are authentic

Respond Fast

Return 200 immediately and process asynchronously for long-running tasks

Handle Duplicates

Use deliveryId for idempotency - you may receive the same event multiple times

Monitor Health

Check consecutiveFailures and circuitOpenedAt to catch issues early

Troubleshooting

Possible causes: - Webhook is not subscribed to the event type - Webhook is disabled (isActive: false) - Circuit breaker is open (check circuitOpenedAt) Solutions: - Verify event subscriptions in webhook configuration - Check if webhook is active - Reset circuit breaker if needed
Possible causes: - Using wrong signing secret - Modifying payload before verification - Encoding issues Solutions: - Verify you’re using the original signing secret - Verify the raw request body, not parsed JSON - Ensure UTF-8 encoding
Cause: Too many consecutive failures triggered the circuit breaker Solutions: 1. Fix the underlying issue (endpoint availability, authentication, etc.) 2. Use the test endpoint to verify connectivity 3. Reset the circuit breaker
Possible causes: - Event occurred before webhook was configured - Event type not in subscription list Note: Webhooks only deliver events that occur after configuration. For historical data, use the API to poll for past events.

Next Steps

Webhook Resource

Detailed webhook configuration reference

API Reference

Complete webhook API documentation

Interviews

Learn about interview events and data

Error Handling

Handle webhook delivery errors