Skip to main content
Prerequisites: Before implementing Find All webhooks, read Webhook Setup & Verification for critical information on:
  • Recording your webhook secret
  • Verifying HMAC signatures
  • Security best practices
  • Retry policies
This guide focuses on Find All-specific webhook events and payloads.

​
Overview

Webhooks allow you to receive real-time notifications when candidates are discovered, evaluated, or when your Find All runs complete, eliminating the need for constant polling—especially useful for long-running Find All operations that may process many candidates over time.

​
Setup

To register a webhook for a Find All run, include a webhook parameter in your Find All run creation request:
cURL
curl --request POST \
  --url https://api.parallel.ai/v1beta/findall/runs \
  --header "Content-Type: application/json" \
  --header "x-api-key: $PARALLEL_API_KEY" \
  --header "parallel-beta: findall-2025-09-15" \
  --data '{
    "objective": "Find all portfolio companies of Khosla Ventures",
    "entity_type": "companies",
    "match_conditions": [
      {
        "name": "khosla_ventures_portfolio_check",
        "description": "Company must be a portfolio company of Khosla Ventures."
      }
    ],
    "processor": "base",
    "match_limit": 5,
    "webhook": {
      "url": "https://your-domain.com/webhooks/findall",
      "event_types": [
        "findall.candidate.generated",
        "findall.candidate.matched",
        "findall.candidate.unmatched",
        "findall.candidate.enriched",
        "findall.run.completed",
        "findall.run.cancelled",
        "findall.run.failed"
      ]
    }
  }

​
Webhook Parameters

ParameterTypeRequiredDescription
urlstringYesYour webhook endpoint URL. Can be any domain.
event_typesarray[string]YesArray of event types to subscribe to. See Event Types below.

​
Event Types

Find All supports the following webhook event types:
Event TypeDescription
findall.candidate.generatedEmitted when a new candidate is generated and queued for evaluation
findall.candidate.matchedEmitted when a candidate successfully matches all match conditions
findall.candidate.unmatchedEmitted when a candidate fails to match all conditions
findall.candidate.enrichedEmitted when enrichment data has been extracted for a candidate
findall.run.completedEmitted when a Find All run completes successfully
findall.run.cancelledEmitted when a Find All run is cancelled
findall.run.failedEmitted when a Find All run fails due to an error
You can subscribe to any combination of these event types in your webhook configuration.
For a complete guide to candidate object structure, states, and fields, see Candidates.

​
Webhook Payload Structure

Each webhook payload contains:
  • timestamp: ISO 8601 timestamp of when the event occurred
  • type: Event type
  • data: Event-specific payload (Find All Candidate or Run object)

​
Candidate Events

{
  "type": "findall.candidate.generated",
  "timestamp": "2025-10-27T14:56:05.619331Z",
  "data": {
    "candidate_id": "candidate_2edf2301-f80d-46b9-b17a-7b4a9d577296",
    "name": "Anthropic",
    "url": "https://www.anthropic.com/",
    "description": "Anthropic is an AI safety and research company founded in 2021...",
    "match_status": "generated",
    "output": null,
    "basis": null
  }
}

​
Run Events

{
  "type": "findall.run.completed",
  "timestamp": "2025-10-27T14:58:39.421087Z",
  "data": {
    "findall_id": "findall_40e0ab8c10754be0b7a16477abb38a2f",
    "status": {
      "status": "completed",
      "is_active": false,
      "metrics": {
        "generated_candidates_count": 5,
        "matched_candidates_count": 1
      },
      "termination_reason": "match_limit_met"
    },
    "processor": "base",
    "metadata": {},
    "created_at": "2025-10-27T14:56:05.619331Z",
    "modified_at": "2025-10-27T14:58:39.421087Z"
  }
}

​
Security & Verification

For information on HMAC signature verification, including code examples in multiple languages, see the Webhook Setup Guide - Security & Verification section.

​
Retry Policy

See the Webhook Setup Guide - Retry Policy for details on webhook delivery retry configuration.

​
Best Practices

For webhook implementation best practices, including signature verification, handling duplicates, and async processing, see the Webhook Setup Guide - Best Practices section.
  • Preview: Test queries with ~10 candidates before running full searches
  • Generators and Pricing: Understand processor options, pricing, and selectivity requirements
  • Enrichments: Extract additional structured data for matched candidates
  • Extend Runs: Increase match limits without paying new fixed costs
  • Streaming Events: Receive real-time updates via Server-Sent Events
  • Run Lifecycle: Understand run statuses and how to cancel runs
  • API Reference: Complete endpoint documentation