Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.heymilo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

HeyMilo Webhooks allow you to receive real-time HTTP notifications when key events occur during the candidate interview lifecycle. Instead of polling the API for updates, webhooks push data to your specified endpoint as soon as an event happens — enabling seamless automation, ATS syncing, and custom workflow triggers. With webhooks, you can:
  • Get notified instantly when a candidate starts or completes an interview
  • Receive full interview reports as soon as they are generated
  • Automate downstream actions like ATS updates, email notifications, or scoring pipelines
  • Build event-driven integrations without continuous API polling

​
How Webhooks Work

  1. Register a webhook via the API, specifying a destination URL, the event type you want to subscribe to, and the posting (job) it applies to.
  2. HeyMilo fires an HTTP request to your URL whenever the subscribed event occurs.
  3. Your endpoint receives the payload containing all relevant event data (candidate info, interview details, scores, etc.).
┌──────────┐         Event occurs         ┌────────────────┐
│  HeyMilo │ ──── HTTP POST/GET ────────► │  Your Endpoint │
└──────────┘   (JSON payload)             └────────────────┘

​
Authentication

Webhook API endpoints require authentication using the X-API-KEY header, the same key used for all Public API requests. 
X-API-KEY: your_api_key_here

​
Webhook Event Types

HeyMilo supports the following webhook event types:
Event TypeDescription
interview_startedTriggered when a candidate begins an interview session
interview_completedTriggered when a candidate finishes all steps of an interview
report_availableTriggered when the AI-generated interview report is ready to view

​
Event Lifecycle

A typical candidate journey triggers events in this order: 
interview_started  ──►  interview_completed  ──►  report_available
Note: The report_available event fires after AI analysis is complete, which may occur several seconds to minutes after the interview is marked as completed.

​
Webhook API Endpoints

All webhook endpoints use the base URL: 
https://api.heymilo.network/api/webhook

​
1. Create Webhook

POST /create Register a new webhook to receive event notifications for a specific job posting.

​
Request Body

{
  "posting_id": "posting_123",
  "url": "https://your-domain.com/webhook-endpoint",
  "event_type": "interview_completed",
  "http_method": "post"
}

​
Request Schema

FieldTypeRequiredDescription
posting_idstringYesID of the job posting this webhook applies to
urlstring (URL)YesThe destination URL that will receive the webhook payload
event_typestringYesOne of: interview_started, interview_completed, report_available
http_methodstringNoHTTP method used to deliver the webhook: get or post (default: post)

​
Example Request

curl -X POST "https://api.heymilo.network/api/webhook/create" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "posting_123",
    "url": "https://your-domain.com/webhook-endpoint",
    "event_type": "interview_completed",
    "http_method": "post"
  }'

​
Response

{
  "webhook_id": "webhook_789",
  "posting_id": "posting_123",
  "url": "https://your-domain.com/webhook-endpoint",
  "event_type": "interview_completed",
  "http_method": "post",
  "is_active": true,
  "created_at": 1703097600.0,
  "updated_at": 1703097600.0
}

​
Response Schema

FieldTypeDescription
webhook_idstringUnique identifier for the created webhook
posting_idstringThe job posting this webhook is associated with
urlstringDestination URL for webhook delivery
event_typestringThe subscribed event type
http_methodstringHTTP method used for delivery (get or post)
is_activebooleanWhether the webhook is currently active
created_atfloatUnix timestamp when the webhook was created
updated_atfloatUnix timestamp when the webhook was last modified

​
2. Get Webhook

GET /fetch/{webhook_id} Retrieve a specific webhook configuration by its ID.

​
Path Parameters

ParameterTypeRequiredDescription
webhook_idstringYesThe unique ID of the webhook

​
Example Request

curl -X GET "https://api.heymilo.network/api/webhook/fetch/webhook_789" \
  -H "X-API-KEY: your_api_key_here"

​
Response

{
  "webhook_id": "webhook_789",
  "posting_id": "posting_123",
  "url": "https://your-domain.com/webhook-endpoint",
  "event_type": "interview_completed",
  "http_method": "post",
  "is_active": true,
  "created_at": 1703097600.0,
  "updated_at": 1703097600.0
}

​
3. Get All Webhooks

GET /all Retrieve all webhooks for your workspace, with optional filters.

​
Query Parameters

ParameterTypeRequiredDescription
posting_idstringNoFilter webhooks by job posting ID
event_typestringNoFilter by event type: interview_started, interview_completed, report_available

​
Example Request

curl -X GET "https://api.heymilo.network/api/webhook/all?posting_id=posting_123&event_type=interview_completed" \
  -H "X-API-KEY: your_api_key_here"

​
Response

[
  {
    "webhook_id": "webhook_789",
    "posting_id": "posting_123",
    "url": "https://your-domain.com/webhook-endpoint",
    "event_type": "interview_completed",
    "http_method": "post",
    "is_active": true,
    "created_at": 1703097600.0,
    "updated_at": 1703097600.0
  },
  {
    "webhook_id": "webhook_790",
    "posting_id": "posting_123",
    "url": "https://your-domain.com/report-endpoint",
    "event_type": "report_available",
    "http_method": "post",
    "is_active": true,
    "created_at": 1703097700.0,
    "updated_at": 1703097700.0
  }
]

​
4. Deactivate Webhook

POST /deactivate/{webhook_id} Deactivate an existing webhook. Deactivated webhooks will no longer receive event notifications.

​
Path Parameters

ParameterTypeRequiredDescription
webhook_idstringYesThe unique ID of the webhook

​
Example Request

curl -X POST "https://api.heymilo.network/api/webhook/deactivate/webhook_789" \
  -H "X-API-KEY: your_api_key_here"

​
Webhook Payload Schemas

When an event fires, HeyMilo sends an HTTP request to your registered URL with a JSON payload. The payload structure varies by event type. Each event type has a distinct schema — see the full payloads and field-by-field breakdowns below.

​
Payload: interview_started

Sent when a candidate begins an interview session. 
{
  "interview_id": "A1B2C3D4E5F60718",
  "posting_id": "F9E8D7C6",
  "timestamp": 1770816760.310334,
  "metadata": {
    "candidate_name": "Jane Doe",
    "candidate_email": "jane.doe@example.com",
    "candidate_id": "B4C5D6E7",
    "metadata": {
      "source": "user_ingestion",
      "job_id": "F9E8D7C6"
    }
  }
}

​
interview_started Payload Schema

FieldTypeDescription
interview_idstringUnique identifier for the interview
posting_idstringThe job posting ID
timestampfloatUnix timestamp when the interview started
metadataobjectCandidate metadata object (see below)
Candidate Metadata Object:
FieldTypeDescription
candidate_namestringCandidate’s full name
candidate_emailstringCandidate’s email address
candidate_idstringUnique identifier for the candidate
metadataobject/nullAdditional ingestion metadata (can be null). See inner metadata below.
Inner Metadata Object (nullable):
FieldTypeDescription
sourcestringHow the candidate was ingested (e.g., user_ingestion)
job_idstringThe job/posting ID associated with the ingestion
Note: The inner metadata object can be null if no additional ingestion context is available.

​
Payload: interview_completed

Sent when a candidate finishes all required steps of an interview. 
{
  "interview_id": "A1B2C3D4E5F60718",
  "agent_conversation_id": "",
  "parent_conversation_id": "7A8B9C0D1E2F3A4B",
  "engagement_id": "",
  "posting_id": "F9E8D7C6",
  "timestamp": 1770810397.0832531,
  "workflow_completed": true,
  "completion_timestamp": 1770810397.0827055
}

​
interview_completed Payload Schema

FieldTypeDescription
interview_idstringUnique identifier for the interview
agent_conversation_idstringConversation ID for the agent interaction (empty string if not applicable)
parent_conversation_idstringParent conversation ID linking related interview sessions
engagement_idstringEngagement tracking ID (empty string if not applicable)
posting_idstringThe job posting ID
timestampfloatUnix timestamp when the event was emitted
workflow_completedbooleanWhether the full agentic workflow has been completed
completion_timestampfloatUnix timestamp when the interview was actually completed

​
Payload: report_available

Sent when the AI-generated interview report is ready. This is the most comprehensive payload, containing the full analysis data: scores, highlights, scorecard, communication evaluation, transcript, interview data model, company info, and posting info. 
{
  "interview_id": "A1B2C3D4E5F60718",
  "posting_id": "F9E8D7C6",
  "metadata": {
    "candidate_name": "Jane Doe",
    "candidate_email": "jane.doe@example.com",
    "candidate_id": "B4C5D6E7F8091A2B",
    "metadata": {
      "candidate_metadata_id": "550e8400-e29b-41d4-a716-446655440000",
      "resume_url": "https://example.cdn.heymilo.ai/WORKSPACE123/source/Jane_Doe_12345678.pdf"
    }
  },
  "report_url": "https://cdn.heymilo.ai/reports/MOCK_REPORT_HASH/jane-doe-2026-02-11.pdf",
  "timestamp": 1770817943.3959253,
  "interview_type": "web_interview",
  "agentic_data": {
    "web_interview_info": {
      "summary": {
        "interview_id": "A1B2C3D4E5F60718",
        "highlights": [
          "Demonstrated strong understanding of core technical concepts.",
          "Provided clear examples of past project experience with measurable outcomes.",
          "Communicated ideas concisely and showed good problem-solving approach."
        ],
        "lowlights": [
          "Did not elaborate on experience with distributed systems.",
          "Missed opportunity to connect leadership experience to the role requirements."
        ],
        "match_score": 78
      },
      "scorecard": {
        "interview_id": "A1B2C3D4E5F60718",
        "match_details": [
          "Demonstrated strong understanding of core technical concepts.",
          "Provided clear examples of past project experience with measurable outcomes.",
          "Did not elaborate on experience with distributed systems.",
          "Missed opportunity to connect leadership experience to the role requirements.",
          "Communicated ideas concisely and showed good problem-solving approach."
        ],
        "questions": [
          {
            "question_id": "Q1A2B3C4",
            "question": "Can you walk me through your professional background and key achievements in your recent roles?",
            "evaluation_summary": "Provided a clear career overview.\nMentioned specific companies and roles.\nDid not fully connect experience to this position.\nMissing some quantitative achievements.",
            "evaluation_criteria": "A good answer provides a clear, concise summary of relevant work experience, highlighting key roles, responsibilities, and achievements aligned with the position.",
            "preview_timestamp": 28,
            "evaluation_score": 7,
            "rank": 1,
            "chat_transcript": [
              {
                "speaker": "Candidate",
                "text": "Sure, I started my career at ...",
                "timestamp": 28,
                "timestamp_str": "00:28"
              }
            ],
            "score_of_1": "Very vague, unclear, or incomplete overview. Missing company names, roles, or timelines. No achievements or impact mentioned.",
            "score_of_5": "Gives a clear, chronological flow of career steps. Mentions companies and role titles. Provides relevant achievements and connects experience to the role.",
            "score_weight": 5,
            "not_scored": false
          },
          {
            "question_id": "Q5D6E7F8",
            "question": "Describe a challenging project you led and how you handled obstacles along the way.",
            "evaluation_summary": "Provided general insights on project challenges.\nArticulated team coordination well.\nCould have gone deeper on measurable impact.",
            "evaluation_criteria": "A good answer describes a specific project, the obstacles faced, actions taken, and outcomes achieved with clarity and structure.",
            "preview_timestamp": 274,
            "evaluation_score": 6,
            "rank": 2,
            "chat_transcript": [
              {
                "speaker": "Candidate",
                "text": "One of the most challenging projects was when ...",
                "timestamp": 274,
                "timestamp_str": "04:34"
              },
              {
                "speaker": "Candidate",
                "text": "We ended up restructuring the approach by ...",
                "timestamp": 418,
                "timestamp_str": "06:58"
              }
            ],
            "score_of_1": "A weak answer is vague, lacks specific details, and fails to describe actions taken or outcomes achieved.",
            "score_of_5": "A strong answer clearly describes the project, obstacles, actions, and outcomes with specific details and measurable results.",
            "score_weight": 5,
            "not_scored": false
          }
        ],
        "tags": [
          "Technical Skills",
          "Project Leadership",
          "Problem Solving"
        ]
      },
      "communication": {
        "interview_id": "A1B2C3D4E5F60718",
        "speech_score": -1,
        "evaluations": [],
        "template_id": null
      },
      "transcript": {
        "interview_id": "A1B2C3D4E5F60718",
        "transcript": [
          {
            "speaker": "bot",
            "text": "Hi, Jane Doe. Thanks for taking the time to meet with me. My name is Sarah, and I'm the AI interviewer. How is your day going so far?",
            "timestamp": 0,
            "timestamp_str": "00:00"
          },
          {
            "speaker": "user",
            "text": "Thank you. Have a nice day.",
            "timestamp": 827,
            "timestamp_str": "13:47"
          },
          {
            "speaker": "bot",
            "text": "Thank you for your time, Jane Doe. I appreciate you completing the interview.",
            "timestamp": 830,
            "timestamp_str": "13:50"
          }
        ]
      },
      "audio_recording_link": "https://cdn.heymilo.ai/audio/merged/1770817889-MOCK01/tmp_audio.wav",
      "video_recording_link": "https://cdn.heymilo.ai/videos/merged/1770817901-MOCK02/tmp_video.mp4"
    }
  },
  "interview_data_model": {
    "interview_id": "A1B2C3D4E5F60718",
    "details": {
      "interview_id": "A1B2C3D4E5F60718",
      "candidate_id": "B4C5D6E7F8091A2B",
      "interviewed_on": 1770817918.4658782,
      "score": 0,
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "actions": null,
      "status": null,
      "workflow_status": {
        "interview_id": "A1B2C3D4E5F60718",
        "step_by_step": [
          {
            "complete": true,
            "required": false,
            "order": 1,
            "id": "web_interview",
            "started": true,
            "details": {
              "details": "Raw Interview Data Has Been Processed",
              "title": "Interview Processed Successfully",
              "description": "Candidate has attended the interview and completed it"
            },
            "raw_status": "INTERVIEW_PROCESSED_RAW_FILES",
            "last_updated_timestamp": 1770817918.4658782,
            "knocked_out": false,
            "completion_percentage": 1,
            "completion_metadata": null,
            "is_analyzing_call": false,
            "total_duration": null,
            "state_flags": {
              "is_completed": true,
              "is_incomplete": false,
              "is_analyzing_call": false,
              "is_in_progress": false
            }
          }
        ],
        "all_complete": true,
        "last_engagement": 1770817918.4658782,
        "metadata": null
      },
      "metadata": {
        "resume": null,
        "web_interview": {
          "final_score": 78,
          "skill_highlights": [
            "Technical Skills",
            "Project Leadership",
            "Problem Solving"
          ],
          "audio_recording_link": "https://cdn.heymilo.ai/audio/merged/1770817889-MOCK01/tmp_audio.wav",
          "video_recording_link": "https://cdn.heymilo.ai/videos/merged/1770817901-MOCK02/tmp_video.mp4"
        },
        "sms": null,
        "form": null
      },
      "candidate_feedback": null,
      "candidate_next_steps": null,
      "candidate_interview_url": "https://gointerview.co/example-company/i/A1B2C3D4E5F60718"
    },
    "company_info": {
      "company_id": "COMP1234",
      "workspace_id": "WS5678",
      "created_at": 1758332488.5218983,
      "updated_at": null,
      "created_by": "email|abc123def456",
      "name": "Example Corp",
      "image_url": "https://heymilo-west-0.s3.us-west-2.amazonaws.com/airstrip/WS5678/example-logo.png",
      "intro_message": null,
      "company_background": null,
      "voice_id": null,
      "knowledge_base": null,
      "interview_domain": null,
      "interview_domain_id": null,
      "sender_email_id": null,
      "address": null,
      "address_data": null,
      "timezone": null,
      "base_web_interview_config": {
        "backdrop_image_url": null,
        "avatar_image_url": null,
        "remove_heymilo_branding": null,
        "intro_message": null,
        "outro_message": null,
        "welcome_back_message": null
      },
      "message_settings": null,
      "sms_agent_config": null,
      "pdf_generation_config": null,
      "cheat_detection": null,
      "allow_white_labeling": null,
      "disable_all_candidate_communications": null,
      "interview_completion_confidence_threshold": 0.7,
      "retention_policy_days": null,
      "video_cheat_detection_enabled": null,
      "form_agent_enabled": null,
      "calendar_management_enabled": null,
      "email_templates_enabled": null,
      "phone_calls_enabled": null,
      "profile_picture_processing": null,
      "chat_agent_enabled": null,
      "copilot_enabled": null,
      "design_templates_enabled": null,
      "interview_templates_enabled": null,
      "sourcing_configs_enabled": null,
      "pbac_enabled": null,
      "email_report_to_candidate_enabled": null
    },
    "posting_info": {
      "posting_id": "F9E8D7C6",
      "title": "Senior Software Engineer",
      "name": "abc-def-123-456-789",
      "internal_name": null,
      "description": "<p><strong>About the Role</strong></p><p>We are looking for a Senior Software Engineer to join our growing team...</p>",
      "root_level_configs": {
        "instructions": "Conduct a structured technical interview with the candidate.",
        "company_overview": "Example Corp is a technology company building innovative solutions.",
        "job_overview": null,
        "interview_process_overview": null,
        "company_overview_delivery_mode": "summarized_delivery",
        "job_overview_delivery_mode": "exact_delivery",
        "interview_process_overview_delivery_mode": "exact_delivery",
        "language": "en",
        "interviewer_name": "Sarah",
        "is_multilingual": false
      },
      "company_id": "COMP1234",
      "created_at": 1769595148.8779235,
      "last_updated": 1769597734.2408419,
      "archived": false,
      "deadline": 1833235200,
      "finalized": true,
      "test_posting": false,
      "agentic_workflow": [
        {
          "type": "web_interview",
          "config": {
            "instructions": "Conduct a structured technical interview focusing on backend development and system design.",
            "company_overview": "Example Corp builds innovative cloud-based solutions for enterprise clients.",
            "job_overview": "The role involves designing and implementing scalable backend services.",
            "interview_process_overview": null,
            "company_overview_delivery_mode": null,
            "job_overview_delivery_mode": null,
            "interview_process_overview_delivery_mode": null,
            "language": "en",
            "interviewer_name": "Sarah",
            "is_multilingual": false,
            "video": true,
            "phone_calls_enabled": false,
            "voice_id": "voice-1",
            "interview_type": "voice",
            "prompt_version": "v2",
            "web_interview_config": {
              "backdrop_image_url": "",
              "avatar_image_url": "https://heymilo-west-0.s3.us-west-2.amazonaws.com/airstrip/MOCK/avatar.png",
              "remove_heymilo_branding": null,
              "intro_message": "Hi {{name}}, thanks for taking the time to meet with me! My name is {{interviewer_name}}, and I'm the AI interviewer. How is your day going so far?",
              "outro_message": "Thank you for your time {{name}}, I appreciate you completing the interview!",
              "welcome_back_message": "",
              "min_duration_seconds": null,
              "max_duration_seconds": null,
              "show_transcript": true,
              "candidate_presence_enabled": true,
              "vapi_call_config": {
                "end_call_message": "",
                "idle_message_max_spoken_count": null,
                "idle_timeout_seconds": 10,
                "wait_seconds": 2.4,
                "backoff_seconds": 5,
                "llm_model": null,
                "llm_temperature": 0.7
              }
            },
            "min_evaluation_score": 0,
            "num_questions": 5,
            "cheat_detection_config": {
              "enabled": false,
              "threshold": 70,
              "types": []
            }
          },
          "unique_id": null
        }
      ],
      "step_workflow": {
        "workflow": {
          "workflow_id": "wf_F9E8D7C6",
          "posting_id": "F9E8D7C6",
          "created_at": 1769595148.8779235
        },
        "steps": [
          {
            "step_id": "step_001",
            "workflow_id": "wf_F9E8D7C6",
            "step_type": "web_interview",
            "rank": 1,
            "details": "",
            "created_at": 1769595148.8779235,
            "depends_on": null
          }
        ]
      },
      "phone_number_id": null,
      "sender_email_id": "",
      "email_template_group_id": null,
      "design_template_group_id": null,
      "sourcing_config_ids": [],
      "redirect_url": null,
      "scheduling_url": null,
      "event_slug": null,
      "cal_team_id": null,
      "team_slug": null,
      "mascot_url": "https://heymilo-west-0.s3.us-west-2.amazonaws.com/avatars/mascot/COMP1234/F9E8D7C6/milo_mock.png",
      "mascot_id": "MASCOT123456",
      "days_to_complete": null,
      "ats_metadata": null,
      "allow_sms_comms": false,
      "max_retakes": null,
      "retake_cooldown_days": null,
      "is_template": false,
      "email_report_to_candidate": false
    },
    "web_interview_info": {
      "summary": {
        "interview_id": "A1B2C3D4E5F60718",
        "highlights": [
          "Demonstrated strong understanding of core technical concepts.",
          "Provided clear examples of past project experience with measurable outcomes.",
          "Communicated ideas concisely and showed good problem-solving approach."
        ],
        "lowlights": [
          "Did not elaborate on experience with distributed systems.",
          "Missed opportunity to connect leadership experience to the role requirements."
        ],
        "match_score": 78
      },
      "scorecard": {
        "interview_id": "A1B2C3D4E5F60718",
        "match_details": [
          "Demonstrated strong understanding of core technical concepts.",
          "Provided clear examples of past project experience with measurable outcomes.",
          "Did not elaborate on experience with distributed systems.",
          "Missed opportunity to connect leadership experience to the role requirements.",
          "Communicated ideas concisely and showed good problem-solving approach."
        ],
        "questions": [
          {
            "question_id": "Q1A2B3C4",
            "question": "Can you walk me through your professional background and key achievements in your recent roles?",
            "evaluation_summary": "Provided a clear career overview.\nMentioned specific companies and roles.\nDid not fully connect experience to this position.\nMissing some quantitative achievements.",
            "evaluation_criteria": "A good answer provides a clear, concise summary of relevant work experience.",
            "preview_timestamp": 28,
            "evaluation_score": 7,
            "rank": 1,
            "chat_transcript": [
              {
                "speaker": "Candidate",
                "text": "Sure, I started my career at ...",
                "timestamp": 28,
                "timestamp_str": "00:28"
              }
            ],
            "score_of_1": "Very vague, unclear, or incomplete overview.",
            "score_of_5": "Gives a clear, chronological flow of career steps with relevant achievements.",
            "score_weight": 5,
            "not_scored": false,
            "extracted_text": null
          }
        ],
        "tags": [
          "Technical Skills",
          "Project Leadership",
          "Problem Solving"
        ]
      },
      "communication": {
        "interview_id": "A1B2C3D4E5F60718",
        "speech_score": -1,
        "evaluations": [],
        "template_id": null
      },
      "transcript": {
        "interview_id": "A1B2C3D4E5F60718",
        "transcript": [
          {
            "speaker": "user",
            "text": "Thank you. Have a nice day.",
            "timestamp": 827,
            "timestamp_str": "13:47"
          },
          {
            "speaker": "bot",
            "text": "Thank you for your time, Jane Doe. I appreciate you completing the interview.",
            "timestamp": 830,
            "timestamp_str": "13:50"
          }
        ]
      },
      "audio_recording_link": "https://cdn.heymilo.ai/audio/merged/1770817889-MOCK01/tmp_audio.wav",
      "video_recording_link": "https://cdn.heymilo.ai/videos/merged/1770817901-MOCK02/tmp_video.mp4"
    },
    "resume_interview_info": null,
    "sms_interview_info": null,
    "form_interview_info": null
  }
}

​
report_available Top-Level Schema

FieldTypeDescription
interview_idstringUnique identifier for the interview
posting_idstringThe job posting ID
metadataobjectCandidate metadata (same structure as interview_started)
report_urlstringDirect URL to download the generated PDF report
timestampfloatUnix timestamp when the report became available
interview_typestringType of interview (e.g., web_interview)
agentic_dataobjectAI-generated analysis data (summary, scorecard, transcript, etc.)
interview_data_modelobjectFull interview record with candidate details, company & posting info

​
agentic_data Object

FieldTypeDescription
web_interview_infoobject/nullAI analysis of web/voice interview (present if interview type is web)

​
agentic_data.web_interview_info Object

FieldTypeDescription
summaryobjectHigh-level interview summary with highlights and match score
scorecardobjectDetailed question-by-question scoring
communicationobjectCommunication and speech quality evaluation
transcriptobjectFull interview transcript
audio_recording_linkstringURL to the audio recording of the interview
video_recording_linkstringURL to the video recording (if video enabled)

​
summary Object

FieldTypeDescription
interview_idstringInterview identifier
highlightsarrayList of candidate strengths (strings)
lowlightsarrayList of candidate weaknesses or gaps (strings)
match_scoreintegerOverall match score (0-100)

​
scorecard Object

FieldTypeDescription
interview_idstringInterview identifier
match_detailsarrayList of match assessment details (strings)
questionsarrayList of scored question objects
tagsarraySkill tags identified during the interview

​
scorecard.questions[] Object

FieldTypeDescription
question_idstringUnique identifier for the question
questionstringThe interview question text
evaluation_summarystringAI-generated summary of the candidate’s answer
evaluation_criteriastringThe criteria used for evaluation
preview_timestampintegerTimestamp offset (seconds) for the answer preview
evaluation_scoreintegerScore for this question (1-10)
rankintegerRanking position of this question
chat_transcriptarrayRelevant transcript excerpts for this question
score_of_1stringDescription of what constitutes the lowest score
score_of_5stringDescription of what constitutes the highest score
score_weightintegerWeight multiplier for this question’s score
not_scoredbooleanWhether this question was excluded from scoring

​
chat_transcript[] Object

FieldTypeDescription
speakerstringWho spoke (Candidate, bot, user)
textstringThe spoken text
timestampintegerTimestamp offset in seconds from interview start
timestamp_strstringHuman-readable timestamp (e.g., "04:34")

​
communication Object

FieldTypeDescription
interview_idstringInterview identifier
speech_scorefloatOverall speech/communication score (-1 if not scored)
evaluationsarrayList of communication evaluation objects (can be empty)
template_idstring/nullTemplate ID used for evaluation (if applicable)

​
transcript Object

FieldTypeDescription
interview_idstringInterview identifier
transcriptarrayList of transcript entry objects

​
interview_data_model Object

FieldTypeDescription
interview_idstringUnique identifier for the interview
detailsobjectCore interview details (candidate info, workflow, metadata)
company_infoobjectFull company/workspace configuration
posting_infoobjectFull job posting configuration
web_interview_infoobject/nullWeb interview analysis (duplicated from agentic_data)
resume_interview_infoobject/nullResume screening analysis (null if no resume step)
sms_interview_infoobject/nullSMS screening analysis (null if no SMS step)
form_interview_infoobject/nullForm screening analysis (null if no form step)

​
interview_data_model.details Object

FieldTypeDescription
interview_idstringInterview identifier
candidate_idstringUnique identifier for the candidate
interviewed_onfloatUnix timestamp when the interview was conducted
scorefloatOverall score
namestringCandidate’s full name
emailstringCandidate’s email address
actionsobject/nullAvailable actions for this interview
statusstring/nullInterview status
workflow_statusobjectDetailed workflow step statuses
metadataobjectPer-stage metadata (resume, web_interview, sms, form)
candidate_feedbackobject/nullCandidate’s feedback on the interview
candidate_next_stepsobject/nullNext steps for the candidate
candidate_interview_urlstringThe candidate-facing interview URL

​
workflow_status Object

FieldTypeDescription
interview_idstringInterview identifier
step_by_steparrayList of workflow step status objects
all_completebooleanWhether all required steps are complete
last_engagementfloatUnix timestamp of the last candidate interaction
metadataobject/nullAdditional workflow metadata

​
workflow_status.step_by_step[] Object

FieldTypeDescription
completebooleanWhether this step is complete
requiredbooleanWhether this step is required
orderintegerPosition in the workflow sequence (1-based)
idstringStep identifier (e.g., web_interview, resume_upload)
startedbooleanWhether the candidate has started this step
detailsobject/nullHuman-readable status details (details, title, description)
raw_statusstringInternal status code (e.g., INTERVIEW_PROCESSED_RAW_FILES)
last_updated_timestampfloatUnix timestamp of the last update to this step
knocked_outbooleanWhether the candidate was disqualified at this step
completion_percentagefloatStep completion progress (0 to 1)
completion_metadataobject/nullAdditional completion metadata
is_analyzing_callbooleanWhether AI analysis is still in progress
total_durationfloat/nullTotal duration of the step in seconds
state_flagsobjectBoolean state flags for the step

​
state_flags Object

FieldTypeDescription
is_completedbooleanWhether the step is fully completed
is_incompletebooleanWhether the step is incomplete
is_analyzing_callbooleanWhether AI analysis is in progress
is_in_progressbooleanWhether the step is currently in progress

​
details.metadata Object

FieldTypeDescription
resumeobject/nullResume metadata (null if no resume step)
web_interviewobject/nullWeb interview metadata (score, highlights, recording links)
smsobject/nullSMS screening metadata (null if no SMS step)
formobject/nullForm screening metadata (null if no form step)

​
details.metadata.web_interview Object

FieldTypeDescription
final_scorefloatFinal interview score
skill_highlightsarrayList of skill tags (strings)
audio_recording_linkstringURL to audio recording
video_recording_linkstringURL to video recording

​
company_info Object

FieldTypeDescription
company_idstringUnique company identifier
workspace_idstringWorkspace identifier
created_atfloatUnix timestamp when the company was created
updated_atfloat/nullUnix timestamp of last update
created_bystringCreator identifier
namestringCompany name
image_urlstringCompany logo URL
intro_messagestring/nullCustom intro message
company_backgroundstring/nullCompany background info
voice_idstring/nullDefault voice ID for interviews
knowledge_baseobject/nullCompany knowledge base configuration
interview_domainstring/nullCustom interview domain
interview_domain_idstring/nullCustom interview domain ID
sender_email_idstring/nullSender email configuration ID
addressstring/nullCompany address
address_dataobject/nullStructured address data
timezonestring/nullCompany timezone
base_web_interview_configobjectDefault web interview config (backdrop, avatar, branding)
message_settingsobject/nullMessaging configuration
sms_agent_configobject/nullSMS agent configuration
pdf_generation_configobject/nullPDF report generation settings
cheat_detectionobject/nullCheat detection configuration
allow_white_labelingboolean/nullWhether white labeling is enabled
disable_all_candidate_communicationsboolean/nullWhether all candidate communications are disabled
interview_completion_confidence_thresholdfloatConfidence threshold for interview completion (0-1)
retention_policy_daysinteger/nullData retention policy in days
video_cheat_detection_enabledboolean/nullWhether video cheat detection is enabled
form_agent_enabledboolean/nullWhether form agent is enabled
calendar_management_enabledboolean/nullWhether calendar management is enabled
email_templates_enabledboolean/nullWhether email templates are enabled
phone_calls_enabledboolean/nullWhether phone calls are enabled
profile_picture_processingboolean/nullWhether profile picture processing is enabled
chat_agent_enabledboolean/nullWhether chat agent is enabled
copilot_enabledboolean/nullWhether copilot is enabled
design_templates_enabledboolean/nullWhether design templates are enabled
interview_templates_enabledboolean/nullWhether interview templates are enabled
sourcing_configs_enabledboolean/nullWhether sourcing configs are enabled
pbac_enabledboolean/nullWhether permissions-based access control is enabled
email_report_to_candidate_enabledboolean/nullWhether email reports to candidates are enabled

​
posting_info Object

FieldTypeDescription
posting_idstringUnique posting identifier
titlestringJob title
namestringURL-friendly posting name
internal_namestring/nullInternal posting name
descriptionstringJob description (HTML)
root_level_configsobjectTop-level agent configuration
company_idstringCompany identifier
created_atfloatUnix timestamp when the posting was created
last_updatedfloatUnix timestamp when the posting was last updated
archivedbooleanWhether the posting is archived
deadlinefloatPosting deadline (Unix timestamp)
finalizedbooleanWhether the posting is finalized
test_postingbooleanWhether this is a test posting
agentic_workflowarrayList of agent workflow steps with configurations
step_workflowobjectWorkflow definition with steps and dependencies
phone_number_idstring/nullAssociated phone number ID
sender_email_idstringSender email ID
email_template_group_idstring/nullEmail template group ID
design_template_group_idstring/nullDesign template group ID
sourcing_config_idsarrayList of sourcing config IDs
redirect_urlstring/nullPost-interview redirect URL
scheduling_urlstring/nullScheduling page URL
event_slugstring/nullCalendar event slug
cal_team_idstring/nullCalendar team ID
team_slugstring/nullTeam slug
mascot_urlstringMascot image URL
mascot_idstringMascot identifier
days_to_completeinteger/nullDays allowed to complete the interview
ats_metadataobject/nullATS integration metadata
allow_sms_commsbooleanWhether SMS communications are enabled
max_retakesinteger/nullMaximum number of interview retakes
retake_cooldown_daysinteger/nullCooldown period between retakes
is_templatebooleanWhether this posting is a template
email_report_to_candidatebooleanWhether to email reports to candidates

​
Setting Up Webhooks

​
Step 1: Prepare Your Endpoint

Your webhook endpoint must be a publicly accessible URL that can receive HTTP requests. The endpoint should:
  • Accept POST (or GET) requests
  • Return a 200 status code to acknowledge receipt
  • Process the payload asynchronously if heavy processing is required
Example endpoint (Node.js / Express): 
app.post("/webhook/heymilo", (req, res) => {
  const event = req.body;

  console.log(`Interview ID: ${event.interview_id}`);
  console.log(`Posting ID: ${event.posting_id}`);

  // Process the event asynchronously
  processWebhookEvent(event);

  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
});
Example endpoint (Python / FastAPI): 
from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook/heymilo")
async def handle_webhook(request: Request):
    event = await request.json()

    print(f"Interview ID: {event['interview_id']}")
    print(f"Posting ID: {event['posting_id']}")

    # Process the event
    await process_webhook_event(event)

    return {"received": True}

​
Step 2: Register the Webhook

Use the Create Webhook API to register your endpoint for the desired event type and job posting. 
curl -X POST "https://api.heymilo.network/api/webhook/create" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "your_posting_id",
    "url": "https://your-domain.com/webhook/heymilo",
    "event_type": "interview_completed",
    "http_method": "post"
  }'

​
Step 3: Verify Delivery

After registering, trigger a test event (e.g., start an interview for a test candidate) and confirm your endpoint receives the payload. Check the response status and payload structure to ensure your integration handles the data correctly.

​
Multiple Webhooks Per Posting

You can register multiple webhooks for the same posting to subscribe to different event types or send events to different endpoints. Example: Subscribe to all events for a single posting 
# Webhook for interview started
curl -X POST "https://api.heymilo.network/api/webhook/create" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "posting_123",
    "url": "https://your-domain.com/webhook/started",
    "event_type": "interview_started"
  }'

# Webhook for interview completed
curl -X POST "https://api.heymilo.network/api/webhook/create" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "posting_123",
    "url": "https://your-domain.com/webhook/completed",
    "event_type": "interview_completed"
  }'

# Webhook for report available
curl -X POST "https://api.heymilo.network/api/webhook/create" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "posting_123",
    "url": "https://your-domain.com/webhook/report",
    "event_type": "report_available"
  }'

​
Best Practices

​
Common Use Cases

​
Error Handling

If your endpoint returns a non-200 status code, the webhook delivery is considered failed. Ensure your endpoint is reliable and returns 200 promptly.

​
Common Errors

ScenarioRecommendation
Endpoint returns 4xxCheck your endpoint URL and ensure it accepts the correct HTTP method
Endpoint returns 5xxInvestigate server-side errors in your application
Endpoint unreachableVerify your endpoint is publicly accessible and DNS is configured
Payload parsing failsValidate the Content-Type header and JSON body parsing logic

​
Support

For webhook support and questions: