chore: Return webhook version in the header (#26139)

* init

* add tests

* fix type

* type fix

* fix

* fix tests

* fix test

Author: alishaz-polymath

docs/developing/guides/automation/webhooks.mdx

@@ -59,6 +59,11 @@ All webhook payloads are wrapped in the following structure:
 }
 ```
 
+<Note>
+Webhook payloads are versioned. The version of the payload sent is included in the x-cal-webhook-version HTTP header.
+Example: x-cal-webhook-version: 2021-10-20
+</Note>
+
 Select a version and trigger event to view the example payload:
 
 <Tabs>

packages/features/bookings/lib/handleNewBooking/scheduleNoShowTriggers.integration-test.ts

@@ -265,6 +265,7 @@ describe("scheduleNoShowTriggers Integration", () => {
         payloadTemplate: null,
         secret: null,
         appId: null,
+        version: "2021-10-20",
       },
     });
 
@@ -273,8 +274,8 @@ describe("scheduleNoShowTriggers Integration", () => {
     expect(sendGenericWebhookPayload).toHaveBeenCalledWith(
       expect.objectContaining({
         webhook: expect.objectContaining({
-          id: hostWebhook.id,
           subscriberUrl: "https://example.com/host-webhook",
+          version: "2021-10-20",
         }),
         triggerEvent: WebhookTriggerEvents.AFTER_HOSTS_CAL_VIDEO_NO_SHOW,
         data: expect.objectContaining({
@@ -287,6 +288,11 @@ describe("scheduleNoShowTriggers Integration", () => {
               user_name: "Guest User",
             }),
           ]),
+          webhook: expect.objectContaining({
+            id: hostWebhook.id,
+            subscriberUrl: "https://example.com/host-webhook",
+            version: "2021-10-20",
+          }),
         }),
       })
     );

packages/features/bookings/lib/handleSeats/cancel/cancelAttendeeSeat.ts

@@ -4,6 +4,7 @@ import { getDelegationCredentialOrFindRegularCredential } from "@calcom/app-stor
 import { sendCancelledSeatEmailsAndSMS } from "@calcom/emails/email-manager";
 import { updateMeeting } from "@calcom/features/conferencing/lib/videoClient";
 import { WorkflowRepository } from "@calcom/features/ee/workflows/repositories/WorkflowRepository";
+import type { WebhookVersion } from "@calcom/features/webhooks/lib/interface/IWebhookRepository";
 import sendPayload from "@calcom/features/webhooks/lib/sendOrSchedulePayload";
 import type { EventPayloadType, EventTypeInfo } from "@calcom/features/webhooks/lib/sendPayload";
 import { getRichDescription } from "@calcom/lib/CalEventParser";
@@ -31,6 +32,7 @@ async function cancelAttendeeSeat(
       payloadTemplate: string | null;
       appId: string | null;
       secret: string | null;
+      version: WebhookVersion;
     }[];
     evt: CalendarEvent;
     eventTypeInfo: EventTypeInfo;

packages/features/bookings/lib/service/InstantBookingCreateService.ts

@@ -27,6 +27,7 @@ import { Prisma } from "@calcom/prisma/client";
 import { BookingStatus, WebhookTriggerEvents } from "@calcom/prisma/enums";
 
 import { instantMeetingSubscriptionSchema as subscriptionSchema } from "../dto/schema";
+import { WebhookVersion } from "../../../webhooks/lib/interface/IWebhookRepository";
 
 interface IInstantBookingCreateServiceDependencies {
   prismaClient: PrismaClient;
@@ -70,6 +71,7 @@ const handleInstantMeetingWebhookTrigger = async (args: {
         payloadTemplate: true,
         appId: true,
         secret: true,
+        version: true,
       },
     });
 
@@ -80,7 +82,10 @@ const handleInstantMeetingWebhookTrigger = async (args: {
         secretKey: sub.secret,
         triggerEvent: eventTrigger,
         createdAt: new Date().toISOString(),
-        webhook: sub,
+        webhook: {
+          ...sub,
+          version: sub.version as WebhookVersion,
+        },
         data: webhookData,
       }).catch((e) => {
         console.error(

packages/features/tasker/tasks/sendWebook.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+import { WebhookVersion } from "@calcom/features/webhooks/lib/interface/IWebhookRepository";
 import sendPayload from "@calcom/features/webhooks/lib/sendPayload";
 
 const sendWebhookPayloadSchema = z.object({
@@ -10,6 +11,7 @@ const sendWebhookPayloadSchema = z.object({
     subscriberUrl: z.string().url(),
     appId: z.string().nullable(),
     payloadTemplate: z.string().nullable(),
+    version: z.nativeEnum(WebhookVersion),
   }),
   // TODO: Define the data schema
   data: z.any(),
@@ -22,7 +24,6 @@ export async function sendWebhook(payload: string): Promise<void> {
     );
     await sendPayload(secretKey, triggerEvent, createdAt, webhook, data);
   } catch (error) {
-    // ... handle error
     console.error(error);
     throw error;
   }

packages/features/tasker/tasks/triggerFormSubmittedNoEvent/triggerFormSubmittedNoEventWebhook.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import type { FORM_SUBMITTED_WEBHOOK_RESPONSES } from "@calcom/app-store/routing-forms/lib/formSubmissionUtils";
 import incompleteBookingActionFunctions from "@calcom/app-store/routing-forms/lib/incompleteBooking/actionFunctions";
+import { DEFAULT_WEBHOOK_VERSION, WebhookVersion } from "@calcom/features/webhooks/lib/interface/IWebhookRepository";
 import { sendGenericWebhookPayload } from "@calcom/features/webhooks/lib/sendPayload";
 import prisma from "@calcom/prisma";
 
@@ -23,6 +24,7 @@ export const ZTriggerFormSubmittedNoEventWebhookPayloadSchema = z.object({
     appId: z.string().nullable(),
     payloadTemplate: z.string().nullable(),
     secret: z.string().nullable(),
+    version: z.nativeEnum(WebhookVersion).optional(),
   }),
   responseId: z.number(),
   responses: z.any(),
@@ -55,7 +57,12 @@ export async function triggerFormSubmittedNoEventWebhook(payload: string): Promi
     secretKey: webhook.secret,
     triggerEvent: "FORM_SUBMITTED_NO_EVENT",
     createdAt: new Date().toISOString(),
-    webhook,
+    webhook: {
+      subscriberUrl: webhook.subscriberUrl,
+      appId: webhook.appId,
+      payloadTemplate: webhook.payloadTemplate,
+      version: webhook.version ?? DEFAULT_WEBHOOK_VERSION,
+    },
     data: {
       formId: form.id,
       formName: form.name,

packages/features/tasker/tasks/triggerNoShow/common.ts

@@ -33,14 +33,19 @@ export function sendWebhookPayload(
   participants: ParticipantsWithEmail,
   originalRescheduledBooking?: OriginalRescheduledBooking,
   hostEmail?: string
-): Promise<any> {
+): Promise<{ ok: boolean; status: number } | void> {
   const maxStartTimeHumanReadable = dayjs.unix(maxStartTime).format("YYYY-MM-DD HH:mm:ss Z");
 
   return sendGenericWebhookPayload({
     secretKey: webhook.secret,
     triggerEvent,
     createdAt: new Date().toISOString(),
-    webhook,
+    webhook: {
+      subscriberUrl: webhook.subscriberUrl,
+      appId: webhook.appId,
+      payloadTemplate: webhook.payloadTemplate,
+      version: webhook.version,
+    },
     data: {
       title: booking.title,
       bookingId: booking.id,

packages/features/tasker/tasks/triggerNoShow/schema.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import { TIME_UNIT } from "@calcom/features/ee/workflows/lib/constants";
 import { WebhookTriggerEvents } from "@calcom/prisma/enums";
+import { WebhookVersion } from "../../../webhooks/lib/interface/IWebhookRepository";
 
 const commonSchema = z.object({
   triggerEvent: z.enum([
@@ -20,6 +21,7 @@ export const ZWebhook = z.object({
   timeUnit: z.enum(TIME_UNIT),
   eventTriggers: z.array(z.string()),
   payloadTemplate: z.string().nullable(),
+  version: z.nativeEnum(WebhookVersion),
 });
 
 export type TWebhook = z.infer<typeof ZWebhook>;

packages/features/tasker/tasks/triggerNoShow/triggerGuestNoShow.test.ts

@@ -21,6 +21,7 @@ import { calculateMaxStartTime } from "./common";
 import { getMeetingSessionsFromRoomName } from "./getMeetingSessionsFromRoomName";
 import type { TSendNoShowWebhookPayloadSchema } from "./schema";
 import { triggerGuestNoShow } from "./triggerGuestNoShow";
+import { WebhookVersion } from "../../../webhooks/lib/interface/IWebhookRepository";
 
 vi.mock("@calcom/features/tasker/tasks/triggerNoShow/getMeetingSessionsFromRoomName", () => ({
   getMeetingSessionsFromRoomName: vi.fn(),
@@ -141,6 +142,7 @@ describe("Trigger Guest No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({
@@ -327,6 +329,7 @@ describe("Trigger Guest No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({
@@ -552,6 +555,7 @@ describe("Trigger Guest No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({
@@ -737,6 +741,7 @@ describe("Trigger Guest No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({
@@ -889,6 +894,7 @@ describe("Trigger Guest No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({

packages/features/tasker/tasks/triggerNoShow/triggerHostNoShow.test.ts

@@ -21,6 +21,7 @@ import { calculateMaxStartTime } from "./common";
 import { getMeetingSessionsFromRoomName } from "./getMeetingSessionsFromRoomName";
 import type { TSendNoShowWebhookPayloadSchema } from "./schema";
 import { triggerHostNoShow } from "./triggerHostNoShow";
+import { WebhookVersion } from "../../../webhooks/lib/interface/IWebhookRepository";
 
 vi.mock("@calcom/features/tasker/tasks/triggerNoShow/getMeetingSessionsFromRoomName", () => ({
   getMeetingSessionsFromRoomName: vi.fn(),
@@ -133,6 +134,7 @@ describe("Trigger Host No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({
@@ -298,6 +300,7 @@ describe("Trigger Host No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({
@@ -503,6 +506,7 @@ describe("Trigger Host No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({
@@ -653,6 +657,7 @@ describe("Trigger Host No Show:", () => {
         timeUnit: TimeUnit.MINUTE,
         payloadTemplate: null,
         secret: null,
+        version: WebhookVersion.V_2021_10_20,
       };
 
       const payload = JSON.stringify({