chore: add cancelled webhook event (#1608)

apps/documentation/pages/developers/webhooks.mdx

@@ -21,6 +21,7 @@ Documenso supports Webhooks and allows you to subscribe to the following events:
 - `document.signed`
 - `document.completed`
 - `document.rejected`
+- `document.cancelled`
 
 ## Create a webhook subscription
 
@@ -37,7 +38,7 @@ Clicking on the "**Create Webhook**" button opens a modal to create a new webhoo
 To create a new webhook subscription, you need to provide the following information:
 
 - Enter the webhook URL that will receive the event payload.
-- Select the event(s) you want to subscribe to: `document.created`, `document.sent`, `document.opened`, `document.signed`, `document.completed`, `document.rejected`.
+- Select the event(s) you want to subscribe to: `document.created`, `document.sent`, `document.opened`, `document.signed`, `document.completed`, `document.rejected`, `document.cancelled`.
 - Optionally, you can provide a secret key that will be used to sign the payload. This key will be included in the `X-Documenso-Secret` header of the request.
 
 ![A screenshot of the Create Webhook modal that shows the URL input field and the event checkboxes](/webhook-images/webhooks-page-create-webhook-modal.webp)
@@ -528,6 +529,96 @@ Example payload for the `document.rejected` event:
 }
 ```
 
+Example payload for the `document.rejected` event:
+
+```json
+{
+  "event": "DOCUMENT_CANCELLED",
+  "payload": {
+    "id": 7,
+    "externalId": null,
+    "userId": 3,
+    "authOptions": null,
+    "formValues": null,
+    "visibility": "EVERYONE",
+    "title": "documenso.pdf",
+    "status": "PENDING",
+    "documentDataId": "cm6exvn93006hi02ru90a265a",
+    "createdAt": "2025-01-27T11:02:14.393Z",
+    "updatedAt": "2025-01-27T11:03:16.387Z",
+    "completedAt": null,
+    "deletedAt": null,
+    "teamId": null,
+    "templateId": null,
+    "source": "DOCUMENT",
+    "documentMeta": {
+      "id": "cm6exvn96006ji02rqvzjvwoy",
+      "subject": "",
+      "message": "",
+      "timezone": "Etc/UTC",
+      "password": null,
+      "dateFormat": "yyyy-MM-dd hh:mm a",
+      "redirectUrl": "",
+      "signingOrder": "PARALLEL",
+      "typedSignatureEnabled": true,
+      "language": "en",
+      "distributionMethod": "EMAIL",
+      "emailSettings": {
+        "documentDeleted": true,
+        "documentPending": true,
+        "recipientSigned": true,
+        "recipientRemoved": true,
+        "documentCompleted": true,
+        "ownerDocumentCompleted": true,
+        "recipientSigningRequest": true
+      }
+    },
+    "recipients": [
+      {
+        "id": 7,
+        "documentId": 7,
+        "templateId": null,
+        "email": "mybirihix@mailinator.com",
+        "name": "Zorita Baird",
+        "token": "XkKx1HCs6Znm2UBJA2j6o",
+        "documentDeletedAt": null,
+        "expired": null,
+        "signedAt": null,
+        "authOptions": { "accessAuth": null, "actionAuth": null },
+        "signingOrder": 1,
+        "rejectionReason": null,
+        "role": "SIGNER",
+        "readStatus": "NOT_OPENED",
+        "signingStatus": "NOT_SIGNED",
+        "sendStatus": "SENT"
+      }
+    ],
+    "Recipient": [
+      {
+        "id": 7,
+        "documentId": 7,
+        "templateId": null,
+        "email": "signer@documenso.com",
+        "name": "Signer",
+        "token": "XkKx1HCs6Znm2UBJA2j6o",
+        "documentDeletedAt": null,
+        "expired": null,
+        "signedAt": null,
+        "authOptions": { "accessAuth": null, "actionAuth": null },
+        "signingOrder": 1,
+        "rejectionReason": null,
+        "role": "SIGNER",
+        "readStatus": "NOT_OPENED",
+        "signingStatus": "NOT_SIGNED",
+        "sendStatus": "SENT"
+      }
+    ]
+  },
+  "createdAt": "2025-01-27T11:03:27.730Z",
+  "webhookEndpoint": "https://mywebhooksite.com/mywebhook"
+}
+```
+
 ## Availability
 
 Webhooks are available to individual users and teams.

packages/lib/server-only/document/delete-document.ts

@@ -9,7 +9,7 @@ import type {
   TeamGlobalSettings,
   User,
 } from '@prisma/client';
-import { DocumentStatus, SendStatus } from '@prisma/client';
+import { DocumentStatus, SendStatus, WebhookTriggerEvents } from '@prisma/client';
 
 import { mailer } from '@documenso/email/mailer';
 import DocumentCancelTemplate from '@documenso/email/templates/document-cancel';
@@ -21,10 +21,15 @@ import { FROM_ADDRESS, FROM_NAME } from '../../constants/email';
 import { AppError, AppErrorCode } from '../../errors/app-error';
 import { DOCUMENT_AUDIT_LOG_TYPE } from '../../types/document-audit-logs';
 import { extractDerivedDocumentEmailSettings } from '../../types/document-email';
+import {
+  ZWebhookDocumentSchema,
+  mapDocumentToWebhookDocumentPayload,
+} from '../../types/webhook-payload';
 import type { ApiRequestMetadata } from '../../universal/extract-request-metadata';
 import { createDocumentAuditLogData } from '../../utils/document-audit-logs';
 import { renderEmailWithI18N } from '../../utils/render-email-with-i18n';
 import { teamGlobalSettingsToBranding } from '../../utils/team-global-settings-to-branding';
+import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
 
 export type DeleteDocumentOptions = {
   id: number;
@@ -110,6 +115,13 @@ export const deleteDocument = async ({
       });
   }
 
+  await triggerWebhook({
+    event: WebhookTriggerEvents.DOCUMENT_CANCELLED,
+    data: ZWebhookDocumentSchema.parse(mapDocumentToWebhookDocumentPayload(document)),
+    userId,
+    teamId,
+  });
+
   // Return partial document for API v1 response.
   return {
     id: document.id,

packages/prisma/migrations/20250124135853_add_cancelled_event_webhooks/migration.sql

@@ -0,0 +1,2 @@
+-- AlterEnum
+ALTER TYPE "WebhookTriggerEvents" ADD VALUE 'DOCUMENT_CANCELLED';

packages/prisma/schema.prisma

@@ -176,6 +176,7 @@ enum WebhookTriggerEvents {
   DOCUMENT_SIGNED
   DOCUMENT_COMPLETED
   DOCUMENT_REJECTED
+  DOCUMENT_CANCELLED
 }
 
 model Webhook {