HeyMilo Webhooks

asyncapi: 3.0.0
info:
  title: HeyMilo Webhooks
  version: 2.0.0
  description: >-
    HeyMilo delivers real-time HTTP notifications across the candidate interview
    lifecycle. Register a webhook via the Public REST API (POST /api/v2/webhooks)
    with a destination URL, an event_type, and the posting_id it applies to;
    HeyMilo then fires an HTTP request (POST by default, GET optional) to your URL
    whenever the subscribed event occurs, carrying a JSON payload with candidate
    and interview data. This AsyncAPI document is GENERATED by the API Evangelist
    enrichment pipeline from HeyMilo's published webhook documentation — payload
    fields are modeled from the documented event data, not from a provider-published
    AsyncAPI spec.
  externalDocs:
    description: Webhook Configuration
    url: https://docs.heymilo.ai/api-reference/webhooks/configuration
x-provenance:
  generated: '2026-07-19'
  method: generated
  source: https://docs.heymilo.ai/api-reference/webhooks/configuration
  spec_type: AsyncAPI
defaultContentType: application/json
channels:
  interviewStarted:
    address: interview_started
    description: Triggered when a candidate begins an interview session.
    messages:
      interviewStarted:
        $ref: '#/components/messages/InterviewStarted'
  interviewCompleted:
    address: interview_completed
    description: Triggered when a candidate finishes all steps of an interview.
    messages:
      interviewCompleted:
        $ref: '#/components/messages/InterviewCompleted'
  reportAvailable:
    address: report_available
    description: >-
      Triggered when the AI-generated interview report is ready. Fires after AI
      analysis completes, which may be seconds to minutes after interview_completed.
    messages:
      reportAvailable:
        $ref: '#/components/messages/ReportAvailable'
operations:
  receiveInterviewStarted:
    action: receive
    channel:
      $ref: '#/channels/interviewStarted'
  receiveInterviewCompleted:
    action: receive
    channel:
      $ref: '#/channels/interviewCompleted'
  receiveReportAvailable:
    action: receive
    channel:
      $ref: '#/channels/reportAvailable'
components:
  messages:
    InterviewStarted:
      name: interview_started
      title: Interview started
      payload:
        $ref: '#/components/schemas/WebhookEvent'
    InterviewCompleted:
      name: interview_completed
      title: Interview completed
      payload:
        $ref: '#/components/schemas/WebhookEvent'
    ReportAvailable:
      name: report_available
      title: Report available
      payload:
        $ref: '#/components/schemas/WebhookEvent'
  schemas:
    WebhookEvent:
      type: object
      description: >-
        HeyMilo webhook payload. The documented event data includes candidate
        information, interview details, and scores; exact field shapes are not
        published in a machine-readable schema, so only the documented envelope
        fields are modeled here.
      properties:
        event_type:
          type: string
          enum: [interview_started, interview_completed, report_available]
        posting_id:
          type: string
          description: The job posting (interviewer) this event belongs to.
        interview_id:
          type: string
          description: The interview the event concerns.