[CAL-3718] Improvement in webhooks documentation

Issue Summary

The documentation has mentioned general payload structure for common events like BOOKING_CREATED, BOOKING_RESHEDULED. This isn't the case for all events, for example the payload for RECORDING_READY is as show below

export interface RECORDING_READY {
  type: string
  title: string
  startTime: string
  endTime: string
  organizer: Organizer
  attendees?: AttendeesEntity[] | null
  uid: string
  downloadLink: string
}

When does the MEETING_ENDED webhook trigger, does it trigger at the endDate of booking or when the meeting end call button is pressed.? Upon testing it looks like it is triggered upon the booking end date, but I got payload as undefined for this particular event, which again isn't documented. Is there a webhook that can be triggerred upon the end call button press ?
Is there a guide on how to test each of the webhook locally ? Right now because of the 1st 2 issues mentioned above I can't rely upon the payload structure and handle each event without testing.

Steps to Reproduce

Have webhook setup done
Book a meeting & wait for few hours so that MEETING_ENDED webhook gets triggered (Make sure to add logs to view the payload)
Payload will be logged as undefined

Evidence

{
     triggerEvent: 'BOOKING_CREATED',
     payload: {
       bookerUrl: 'https://cal.com',
       type: 'test',
       title: 'test between Hussam Khatib and Hussam',
       description: '',
       additionalNotes: '',
       customInputs: {},
       startTime: '2024-05-14T18:44:50Z',
       endTime: '2024-05-14T18:45:50Z',
       organizer: {
         id: 64419,
         name: 'Hussam Khatib',
         email: 'XXXX',
         username: 'hussamkhatib',
         timeZone: 'Asia/Calcutta',
         language: [Object],
         timeFormat: 'h:mma',
         utcOffset: 330
       },
       responses: {
         name: [Object],
         email: [Object],
         location: [Object],
         title: [Object],
         notes: [Object],
         guests: [Object],
         rescheduleReason: [Object]
       },
       userFieldsResponses: {},
       attendees: [ [Object] ],
       location: 'integrations:daily',
       destinationCalendar: null,
       hideCalendarNotes: false,
       requiresConfirmation: false,
       eventTypeId: 788720,
       seatsShowAttendees: true,
       seatsPerTimeSlot: null,
       seatsShowAvailabilityCount: true,
       schedulingType: null,
       iCalUID: 'hR5Lzz7BmE1s1erY6Zd5at@Cal.com',
       iCalSequence: 0,
       uid: 'hR5Lzz7BmE1s1erY6Zd5at',
       conferenceData: { createRequest: [Object] },
       videoCallData: {
         type: 'daily_video',
         id: 'ALdi4m4zTcloI3TojObR',
         password: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyIjoiQUxkaTRtNHpUY2xvSTNUb2pPYlIiLCJleHAiOjE3MTY5MjE5NTAsIm8iOnRydWUsImQiOiJiYmQ5OGE3MS0xOWM5LTRiYjEtYTVjNS1jYWYxZWM1YmQxMDUiLCJpYXQiOjE3MTU3MTIyNDJ9.YZadx_BZXTp6yEc3I3rpIX_h9Tay5NiLQouaHOGJWWQ',
         url: 'https://meetco.daily.co/ALdi4m4zTcloI3TojObR'
       },
       appsStatus: [ [Object] ],
       eventTitle: 'test',
       eventDescription: '',
       price: 0,
       currency: 'usd',
       length: 1,
       bookingId: 2030802,
       metadata: {
         videoCallUrl: 'https://app.cal.com/video/hR5Lzz7BmE1s1erY6Zd5at'
       },
       status: 'ACCEPTED'
     },
     reqBody: {
       triggerEvent: 'BOOKING_CREATED',
       createdAt: '2024-05-14T18:44:03.645Z',
       payload: {
         bookerUrl: 'https://cal.com',
         type: 'test',
         title: 'test between Hussam Khatib and Hussam',
         description: '',
         additionalNotes: '',
         customInputs: {},
         startTime: '2024-05-14T18:44:50Z',
         endTime: '2024-05-14T18:45:50Z',
         organizer: [Object],
         responses: [Object],
         userFieldsResponses: {},
         attendees: [Array],
         location: 'integrations:daily',
         destinationCalendar: null,
         hideCalendarNotes: false,
         requiresConfirmation: false,
         eventTypeId: 788720,
         seatsShowAttendees: true,
         seatsPerTimeSlot: null,
         seatsShowAvailabilityCount: true,
         schedulingType: null,
         iCalUID: 'hR5Lzz7BmE1s1erY6Zd5at@Cal.com',
         iCalSequence: 0,
         uid: 'hR5Lzz7BmE1s1erY6Zd5at',
         conferenceData: [Object],
         videoCallData: [Object],
         appsStatus: [Array],
         eventTitle: 'test',
         eventDescription: '',
         price: 0,
         currency: 'usd',
         length: 1,
         bookingId: 2030802,
         metadata: [Object],
         status: 'ACCEPTED'
       }
     }
   }

{
     triggerEvent: 'MEETING_STARTED',
     payload: undefined,
     reqBody: {
       triggerEvent: 'MEETING_STARTED',
       id: 2030837,
       uid: 'b7bUM9yNBpURfEtRy5fSYM',
       idempotencyKey: 'c86af8f1-2d63-5a04-ad8d-d209fc691a56',
       userId: 64419,
       userPrimaryEmail: 'hussamkhatib20@gmail.com',
       eventTypeId: 788720,
       title: 'test between Hussam Khatib and Hussam',
       description: '',
       customInputs: {},
       responses: {
         name: 'Hussam',
         email: 'hussam@shippercrm.com',
         guests: [],
         location: [Object]
       },
       startTime: '2024-05-14T18:49:02.000Z',
       endTime: '2024-05-14T18:50:02.000Z',
       location: 'integrations:daily',
       createdAt: '2024-05-14T18:48:07.759Z',
       updatedAt: null,
       status: 'ACCEPTED',
       paid: false,
       destinationCalendarId: null,
       cancellationReason: null,
       rejectionReason: null,
       dynamicEventSlugRef: null,
       dynamicGroupSlugRef: null,
       rescheduled: null,
       fromReschedule: 'hR5Lzz7BmE1s1erY6Zd5at',
       recurringEventId: null,
       smsReminderNumber: null,
       scheduledJobs: [],
       metadata: {
         videoCallUrl: 'https://app.cal.com/video/hR5Lzz7BmE1s1erY6Zd5at'
       },
       isRecorded: false,
       iCalUID: 'hR5Lzz7BmE1s1erY6Zd5at@Cal.com',
       iCalSequence: 0,
       rating: null,
       ratingFeedback: null,
       noShowHost: null,
       user: {
         email: 'hussamkhatib20@gmail.com',
         name: 'Hussam Khatib',
         timeZone: 'Asia/Calcutta',
         username: 'hussamkhatib'
       },
       attendees: [ [Object] ],
       payment: [],
       references: [],
       appsStatus: [ [Object] ]
     }
   }

_{From SyncLinear.com | CAL-3718}

To address your concerns:

The payload for RECORDING_READY you've mentioned seems to be missing some fields based on the current implementation in the repository. The actual structure includes additional fields such as recording_id, end_ts, room_name, start_ts, status, max_participants, duration, and s3_key. It's important to cross-reference with the latest codebase for the most accurate structure.
The MEETING_ENDED webhook triggers at the booking's end date, not when the end call button is pressed. The issue with the payload being undefined could be due to how properties are accessed; if the base object is null, any further property access will result in undefined.
For local testing of webhook events, you can simulate webhook events by sending test requests that match the expected schema to specific endpoints, as outlined in the repository's documentation. Make sure your environment is correctly set up with the necessary variables for a successful test.

This approach should help you handle each event more reliably and test them effectively in your local environment.

#### Details

**Sources** - [apps/web/pages/api/recorded-daily-video.ts](https://github.com/calcom/cal.com/blob/main/apps/web/pages/api/recorded-daily-video.ts) - [packages/features/bookings/lib/getWebhookPayloadForBooking.ts](https://github.com/calcom/cal.com/blob/main/packages/features/bookings/lib/getWebhookPayloadForBooking.ts) - [packages/features/webhooks/lib/constants.ts](https://github.com/calcom/cal.com/blob/main/packages/features/webhooks/lib/constants.ts) - [packages/features/webhooks/lib/scheduleTrigger.ts](https://github.com/calcom/cal.com/blob/main/packages/features/webhooks/lib/scheduleTrigger.ts) - [apps/api/v1/pages/api/webhooks/_post.ts](https://github.com/calcom/cal.com/blob/main/apps/api/v1/pages/api/webhooks/_post.ts)
**About Dosu** This response is meant to be useful and save you time. It is **not meant to be a precise solution**, but rather a starting point for your own research. Help me be more useful! Please leave a 👍 if this is helpful and 👎 if it is irrelevant.

To continue the conversation, mention @dosu.

calcom / cal.com