asyncapi: 2.6.0
info:
  title: Calendly Webhook Events
  description: >-
    The Calendly Webhook API enables developers to receive real-time
    notifications when scheduling events occur in Calendly. By creating
    webhook subscriptions, applications can automatically receive data
    whenever invitees schedule, cancel, or reschedule meetings, or when
    routing form submissions are created. This eliminates the need for
    polling the API and allows for event-driven integrations that respond
    immediately to changes in scheduling activity. Webhook payloads are
    signed for verification and delivered via HTTP POST to the configured
    callback URL.
  version: '2.0.0'
  contact:
    name: Calendly Developer Support
    url: https://developer.calendly.com/
  license:
    name: Calendly Terms of Service
    url: https://calendly.com/pages/terms
servers:
  production:
    url: 'https://api.calendly.com'
    protocol: https
    description: >-
      Calendly production server. Webhook subscriptions are managed via
      the REST API, and payloads are delivered to the subscriber-configured
      callback URL.
    security:
      - bearerAuth: []
channels:
  /webhook/invitee-created:
    description: >-
      Channel for invitee.created events. Triggered when a new invitee
      schedules a meeting through Calendly. Also triggered as part of a
      reschedule operation (the new booking). The payload includes the
      full invitee resource with event details, contact information, and
      answers to custom questions.
    publish:
      operationId: onInviteeCreated
      summary: Invitee created event
      description: >-
        Fired when a new meeting is scheduled. The webhook delivers the
        full invitee object including name, email, timezone, event URI,
        custom question answers, and tracking parameters. For rescheduled
        events, the new_invitee and old_invitee fields link the new and
        previous bookings.
      message:
        $ref: '#/components/messages/InviteeCreatedEvent'
  /webhook/invitee-canceled:
    description: >-
      Channel for invitee.canceled events. Triggered when an existing
      scheduled event is canceled by either the host or the invitee. Also
      triggered as part of a reschedule operation (the old booking being
      canceled). The payload includes cancellation details and the reason
      if provided.
    publish:
      operationId: onInviteeCanceled
      summary: Invitee canceled event
      description: >-
        Fired when a scheduled meeting is canceled. The payload includes
        the invitee resource with cancellation details, including who
        canceled and the reason. For rescheduled events, the rescheduled
        field is set to true and the new_invitee field links to the
        replacement booking.
      message:
        $ref: '#/components/messages/InviteeCanceledEvent'
  /webhook/routing-form-submission-created:
    description: >-
      Channel for routing_form_submission.created events. Triggered when
      someone submits a routing form, regardless of whether they
      subsequently book a meeting. The payload includes the form
      submission with all questions and answers.
    publish:
      operationId: onRoutingFormSubmissionCreated
      summary: Routing form submission created event
      description: >-
        Fired when a routing form is submitted. The payload includes the
        routing form submission resource with all questions and answers,
        tracking parameters, and a reference to the resulting invitee if
        a booking was made.
      message:
        $ref: '#/components/messages/RoutingFormSubmissionCreatedEvent'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token or OAuth 2.1 access token used to manage
        webhook subscriptions via the REST API.
    webhookSignature:
      type: httpApiKey
      name: Calendly-Webhook-Signature
      in: header
      description: >-
        HMAC signature of the webhook payload for verifying authenticity.
        The signature is computed using the signing key provided when
        creating the webhook subscription.
  messages:
    InviteeCreatedEvent:
      name: invitee.created
      title: Invitee Created
      summary: >-
        Delivered when a new invitee schedules a meeting through Calendly.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WebhookPayload'
      headers:
        type: object
        properties:
          Calendly-Webhook-Signature:
            type: string
            description: >-
              The HMAC signature for payload verification.
      examples:
        - name: InviteeCreatedExample
          summary: A new meeting was scheduled
          payload:
            event: invitee.created
            created_at: '2024-01-15T10:30:00.000000Z'
            created_by: 'https://api.calendly.com/users/abc123'
            payload:
              uri: 'https://api.calendly.com/scheduled_events/evt123/invitees/inv456'
              email: 'jane@example.com'
              name: 'Jane Doe'
              status: active
              timezone: 'America/New_York'
              event: 'https://api.calendly.com/scheduled_events/evt123'
              created_at: '2024-01-15T10:30:00.000000Z'
              updated_at: '2024-01-15T10:30:00.000000Z'
              cancel_url: 'https://calendly.com/cancellations/inv456'
              reschedule_url: 'https://calendly.com/reschedulings/inv456'
    InviteeCanceledEvent:
      name: invitee.canceled
      title: Invitee Canceled
      summary: >-
        Delivered when an invitee or host cancels a scheduled meeting.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WebhookPayload'
      headers:
        type: object
        properties:
          Calendly-Webhook-Signature:
            type: string
            description: >-
              The HMAC signature for payload verification.
      examples:
        - name: InviteeCanceledExample
          summary: A meeting was canceled
          payload:
            event: invitee.canceled
            created_at: '2024-01-16T08:00:00.000000Z'
            created_by: 'https://api.calendly.com/users/abc123'
            payload:
              uri: 'https://api.calendly.com/scheduled_events/evt123/invitees/inv456'
              email: 'jane@example.com'
              name: 'Jane Doe'
              status: canceled
              timezone: 'America/New_York'
              event: 'https://api.calendly.com/scheduled_events/evt123'
              cancellation:
                canceled_by: 'Jane Doe'
                reason: 'Schedule conflict'
                canceler_type: invitee
                created_at: '2024-01-16T08:00:00.000000Z'
              rescheduled: false
    RoutingFormSubmissionCreatedEvent:
      name: routing_form_submission.created
      title: Routing Form Submission Created
      summary: >-
        Delivered when someone submits a routing form, whether or not they
        subsequently book a meeting.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/RoutingFormWebhookPayload'
      headers:
        type: object
        properties:
          Calendly-Webhook-Signature:
            type: string
            description: >-
              The HMAC signature for payload verification.
  schemas:
    WebhookPayload:
      type: object
      description: >-
        The top-level webhook payload delivered to the subscriber callback
        URL for invitee events.
      properties:
        event:
          type: string
          enum:
            - invitee.created
            - invitee.canceled
          description: >-
            The type of event that triggered the webhook.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the webhook event was created in UTC.
        created_by:
          type: string
          format: uri
          description: >-
            The URI of the user associated with the event.
        payload:
          $ref: '#/components/schemas/InviteePayload'
    RoutingFormWebhookPayload:
      type: object
      description: >-
        The top-level webhook payload delivered for routing form submission
        events.
      properties:
        event:
          type: string
          enum:
            - routing_form_submission.created
          description: >-
            The type of event that triggered the webhook.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the webhook event was created in UTC.
        created_by:
          type: string
          format: uri
          description: >-
            The URI of the user associated with the event.
        payload:
          $ref: '#/components/schemas/RoutingFormSubmissionPayload'
    InviteePayload:
      type: object
      description: >-
        The invitee data included in webhook payloads for invitee.created
        and invitee.canceled events.
      properties:
        uri:
          type: string
          format: uri
          description: >-
            The canonical URI of the invitee resource.
        email:
          type: string
          format: email
          description: >-
            The email address of the invitee.
        first_name:
          type: string
          description: >-
            The first name of the invitee.
        last_name:
          type: string
          description: >-
            The last name of the invitee.
        name:
          type: string
          description: >-
            The full name of the invitee.
        status:
          type: string
          enum:
            - active
            - canceled
          description: >-
            The current status of the invitee.
        timezone:
          type: string
          description: >-
            The IANA timezone of the invitee.
        event:
          type: string
          format: uri
          description: >-
            The URI of the associated scheduled event.
        text_reminder_number:
          type: string
          description: >-
            The phone number for text reminders.
        rescheduled:
          type: boolean
          description: >-
            Whether this event is part of a reschedule operation. True on the
            canceled side of a reschedule.
        old_invitee:
          type: string
          format: uri
          description: >-
            The URI of the previous invitee for rescheduled events.
        new_invitee:
          type: string
          format: uri
          description: >-
            The URI of the new invitee for rescheduled events.
        cancel_url:
          type: string
          format: uri
          description: >-
            The URL for the invitee to cancel the event.
        reschedule_url:
          type: string
          format: uri
          description: >-
            The URL for the invitee to reschedule the event.
        cancellation:
          type: object
          description: >-
            Cancellation details, present only for canceled invitees.
          properties:
            canceled_by:
              type: string
              description: >-
                The name of the person who canceled.
            reason:
              type: string
              description: >-
                The reason for cancellation.
            canceler_type:
              type: string
              enum:
                - host
                - invitee
              description: >-
                Whether the host or invitee canceled.
            created_at:
              type: string
              format: date-time
              description: >-
                When the cancellation occurred.
        questions_and_answers:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
                description: >-
                  The text of the custom question.
              answer:
                type: string
                description: >-
                  The invitees answer.
              position:
                type: integer
                description: >-
                  The display position of the question.
          description: >-
            Answers to custom questions on the booking page.
        tracking:
          type: object
          description: >-
            UTM and tracking parameters captured at booking time.
          properties:
            utm_campaign:
              type: string
              description: >-
                The UTM campaign parameter.
            utm_source:
              type: string
              description: >-
                The UTM source parameter.
            utm_medium:
              type: string
              description: >-
                The UTM medium parameter.
            utm_content:
              type: string
              description: >-
                The UTM content parameter.
            utm_term:
              type: string
              description: >-
                The UTM term parameter.
            salesforce_uuid:
              type: string
              description: >-
                The Salesforce UUID if applicable.
        payment:
          type: object
          description: >-
            Payment information if the event type requires payment.
          properties:
            external_id:
              type: string
              description: >-
                The external payment processor ID.
            provider:
              type: string
              description: >-
                The payment provider name.
            amount:
              type: number
              description: >-
                The payment amount.
            currency:
              type: string
              description: >-
                The currency code.
            terms:
              type: string
              description: >-
                The payment terms.
            successful:
              type: boolean
              description: >-
                Whether the payment was successful.
        scheduled_event:
          type: object
          description: >-
            The scheduled event data included in the webhook payload.
          properties:
            uri:
              type: string
              format: uri
              description: >-
                The canonical URI of the scheduled event.
            name:
              type: string
              description: >-
                The name of the event.
            status:
              type: string
              enum:
                - active
                - canceled
              description: >-
                The status of the event.
            start_time:
              type: string
              format: date-time
              description: >-
                The start time in UTC.
            end_time:
              type: string
              format: date-time
              description: >-
                The end time in UTC.
            event_type:
              type: string
              format: uri
              description: >-
                The URI of the event type.
            location:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The location type.
                location:
                  type: string
                  description: >-
                    The location details.
                join_url:
                  type: string
                  format: uri
                  description: >-
                    The URL to join the meeting.
              description: >-
                The event location details.
            event_memberships:
              type: array
              items:
                type: object
                properties:
                  user:
                    type: string
                    format: uri
                    description: >-
                      The URI of the event member.
                  user_email:
                    type: string
                    format: email
                    description: >-
                      The email of the event member.
              description: >-
                The hosts of the event.
            created_at:
              type: string
              format: date-time
              description: >-
                When the event was created.
            updated_at:
              type: string
              format: date-time
              description: >-
                When the event was last updated.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the invitee was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the invitee was last updated.
    RoutingFormSubmissionPayload:
      type: object
      description: >-
        The routing form submission data included in webhook payloads for
        routing_form_submission.created events.
      properties:
        uri:
          type: string
          format: uri
          description: >-
            The canonical URI of the routing form submission.
        routing_form:
          type: string
          format: uri
          description: >-
            The URI of the routing form that was submitted.
        questions_and_answers:
          type: array
          items:
            type: object
            properties:
              question_uuid:
                type: string
                description: >-
                  The UUID of the question.
              question:
                type: string
                description: >-
                  The text of the question.
              answer:
                type: string
                description: >-
                  The respondents answer.
          description: >-
            The questions and answers from the submission.
        tracking:
          type: object
          description: >-
            UTM and tracking parameters captured at submission time.
          properties:
            utm_campaign:
              type: string
              description: >-
                The UTM campaign parameter.
            utm_source:
              type: string
              description: >-
                The UTM source parameter.
            utm_medium:
              type: string
              description: >-
                The UTM medium parameter.
        submitter:
          type: string
          format: uri
          description: >-
            The URI of the invitee created from this submission.
        submitter_type:
          type: string
          description: >-
            The type of submitter.
        created_at:
          type: string
          format: date-time
          description: >-
            When the submission was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            When the submission was last updated.