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:
Interview and analysis events cover every interview in the company, not only the ones you created through this API. An interview a recruiter launched from the InstaView dashboard emits the same interview.* and analysis.* stream as one you created yourself. Filter on the interviewId values you know about if you only want your own.For an ATS integration, a webhook registered on the parent company also receives events for its child companies. Register one endpoint on the parent to cover every tenant, or one per child for separate endpoints — a child’s webhook only ever receives that child’s events, and never a sibling’s.If you register on both a parent and one of its children, that child’s events reach both endpoints as two separate deliveries with different deliveryIds. See Handling duplicates for the key that collapses them — deliveryId will not, by design.

​
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
  • "INTERVIEW_RESCHEDULED" - A follow-up call attempt has been scheduled
  • "INTERVIEW_CANCELLED" - Interview terminated 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

​
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

​
Interview Rescheduled Payload

Sent when a call attempt did not produce a completed interview and a follow-up attempt has been scheduled. This event sits between two call attempts, so unlike the other interview events it does not carry a single callAttemptId — the two attempts are split explicitly.
The candidate’s line was busy, so the system scheduled another attempt on its own.
Field notes:

​
Interview Cancelled Payload

Sent when an interview reaches a terminal state without completing — either cancelled explicitly, or abandoned after exhausting its retry budget.
reason is one of: lastCallAttemptId is absent when the interview was cancelled before any call was placed.
data.status is the event’s status, not the interview’s. This payload always carries status: "CANCELLED", but for reason: "MAX_ATTEMPTS_EXCEEDED" the interview resource itself now reads UNREACHABLE — fetching GET /interviews/{id} after this webhook returns a different value than the payload shows. Branch on reason, not on data.status, and re-read the resource if you mirror interview status into your own system.
There is no API_REQUEST cancellation reason. The public API has no interview-level cancel endpoint — DELETE /interviews/{id} removes the interview outright and cancels its pending webhook deliveries, so no interview.cancelled event is emitted for it. If you need a record of the cancellation, capture it before issuing the delete.

​
Rescheduling a call attempt yourself

PATCH /interviews/{id}/call-attempts/{attemptId} emits interview.rescheduled with reason: "API_REQUEST". Because this endpoint moves an existing attempt rather than ending one and creating another, the same callAttemptId appears in both previousAttempt and nextAttempt, and previousAttempt.status is SCHEDULED — no call took place. This is the only reason value where that holds; for every other reason the two IDs differ.

​
Interview Event Ordering

A given interview emits interview.started once per call attempt, so multiple starts are normal. Exactly one terminal event is emitted per interview — either interview.completed, interview.cancelled, or interview.failed. Two representative sequences:
Before these events existed, retries and cancellations were silent — an integrator saw repeated interview.started events with no explanation for the gaps, and an interview that exhausted its attempts never produced a terminal event at all. If your handler infers state from event ordering, subscribe to both new events.

​
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

​
Delivery Guarantees

At least once, for as long as the retry budget lasts. Every event InstaView records is attempted against each subscribed endpoint, and may be attempted more than once — so design your handler to tolerate a repeat; see Handling duplicates for the keys that collapse them. It is not an unconditional promise of arrival: an endpoint that keeps failing exhausts the retry budget described in Retry Logic, and the delivery is then marked failed and abandoned. What InstaView guarantees is that no recorded event is ever silently dropped on our side — every one is attempted, and a failure to deliver is a visible failed delivery rather than an event that quietly never existed. What “records” means matters, because it is what the guarantee rests on. The moment an interview is cancelled, an analysis finishes, or any other event occurs, InstaView writes that fact to durable storage in the same database transaction as the change itself. Building the payload, resolving which endpoints are subscribed, and queueing the request all happen afterwards, and all of those steps are retried until they succeed — they are internal, so nothing about your endpoint can exhaust them. Only the HTTP delivery itself has a finite budget. So:
  • If the underlying operation is rolled back, no event is sent. There is no window in which you are told an interview was cancelled when it was not.
  • If the operation commits, the event is owed to you even if InstaView restarts, loses a database connection, or fails to read the interview in the instant afterwards. Nothing between the commit and the request can silently discard it.
Ordering is not guaranteed. Events are delivered independently and retried independently, so a retried interview.started can arrive after the interview.completed that followed it. Use the timestamps and identifiers in the payload rather than arrival order. A delivery is in flight only once. Each delivery attempt is claimed exclusively before the request goes out, so overlapping internal retry passes cannot send the same delivery twice in parallel. Duplicates you do see are genuine retries after a failure or timeout, and carry the deliveryId that lets you recognise them. Latency. Ordinary events are sent as soon as their transaction commits, typically within a second. Bulk events — the interview.cancelled fan-out from a cancelled flow run, which can be thousands of interviews — are queued and drained in batches, so expect those to arrive over the following minutes rather than instantly.

​
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. Each attempt reuses the same deliveryId, so a retry is always recognisable as a repeat of the attempt before it.

​
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

​
Handling Duplicates

There are two different kinds of duplicate, and they need different keys. The same delivery arriving twice — a retry after your endpoint timed out, or after it answered non-2xx. Both copies carry the same deliveryId. Track the deliveryId values you have processed and ignore a repeat, as in Be Idempotent below. The same event delivered to two of your endpoints — you registered a webhook on an ATS parent company and on one of its children, so an event in the child matches both configurations. These are genuinely separate deliveries with different deliveryIds, and deliveryId will not collapse them. Match instead on the event name plus the identifier of the occurrence the payload describes:
Do not key on data.interviewId alone for the per-attempt events. One interview emits interview.rescheduled once per retry and interview.started once per attempt; treating those as duplicates of each other silently drops events you wanted. Only interview.cancelled is once-per-interview.
If you register a single endpoint per company — the common case — neither situation beyond ordinary retries arises, and deliveryId on its own is enough.
Both keys are stable across an InstaView restart or failover. Delivery is recovered from durable storage rather than from memory, so a redeployment mid-flight resumes the same delivery rather than starting a new one under a new deliveryId.

​
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