Managing SharePoint Webhooks Using PnP PowerShell

SharePoint Webhooks allow real-time event notifications when changes occur in a SharePoint list or document library. This helps in tracking item creations, updates, deletions, and automating workflows.

Using PnP PowerShell, you can create, retrieve, update, and delete webhooks efficiently.

---

Step 1: Prerequisites

1.1 Install and Update PnP PowerShell

Ensure you have PnP PowerShell installed:

Install-Module PnP.PowerShell -Scope CurrentUser

To update:

powershellCopyEditUpdate-Module PnP.PowerShell

1.2 Connect to SharePoint Online

Run the following command to authenticate:

Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/YourSite" -Interactive

Replace "yourtenant" and "YourSite" accordingly.

Result: You are connected to SharePoint Online.

---

Step 2: Create a Webhook Subscription

A webhook requires:

• List or Library ID
• Notification URL (Endpoint to receive events)
• Expiration Date (Max 6 months)

2.1 Get the List ID

Get-PnPList -Identity "Documents" | Select Id, Title

Result: Retrieves the List ID.

2.2 Register the Webhook

Add-PnPWebhookSubscription -List "Documents" -NotificationUrl "https://yourwebhookreceiver.com/api/notifications" -ExpirationDate (Get-Date).AddMonths(6)

• Replace "Documents" with your list name.
• Replace "https://yourwebhookreceiver.com/api/notifications" with your notification receiver URL.
• The expiration date is set to 6 months from today.

Result: Webhook subscription is created.

---

Step 3: Retrieve Existing Webhook Subscriptions

To view active webhook subscriptions for a list:

Get-PnPWebhookSubscription -List "Documents"

Result: Displays subscription details, including expiration date and notification URL.

---

Step 4: Update a Webhook Subscription

If the notification URL changes, update the webhook:

Update-PnPWebhookSubscription -List "Documents" -Identity "<Subscription-ID>" -NotificationUrl "https://newwebhookurl.com/api/notifications"

To extend the expiration date:

Update-PnPWebhookSubscription -List "Documents" -Identity "<Subscription-ID>" -ExpirationDate (Get-Date).AddMonths(6)

• Replace "<Subscription-ID>" with the actual webhook subscription ID.

Result: Webhook is updated.

---

Step 5: Remove a Webhook Subscription

To delete a webhook:

Remove-PnPWebhookSubscription -List "Documents" -Identity "<Subscription-ID>"

Result: The webhook subscription is removed.

---

Step 6: Handling Webhook Notifications

When a change occurs, SharePoint sends a POST request to your Notification URL with a payload like:

{
  "value": [
    {
      "subscriptionId": "abc123",
      "clientState": "randomString",
      "expirationDateTime": "2025-06-10T12:00:00Z",
      "resource": "lists('Documents')/items(5)",
      "tenantId": "yourTenantID",
      "siteUrl": "https://yourtenant.sharepoint.com/sites/YourSite"
    }
  ]
}

Your API should:

1. Validate the request
2. Process the event (e.g., update a database, trigger a workflow)
3. Respond with HTTP 200 OK

Result: Your service processes SharePoint changes automatically.

---

Step 7: Automate Webhook Management with Power Automate

You can use Power Automate to trigger flows based on webhook notifications.

Example: Power Automate Webhook Workflow

1. Trigger: HTTP Request (Webhook Notification URL)
2. Condition: Check subscriptionId and resource
3. Action:
   • Send an email notification
   • Update a database
   • Log the change

Result: Webhook events are handled in Power Automate.

---

Step 8: Debugging and Monitoring Webhooks

8.1 Check Subscription Status

Get-PnPWebhookSubscription -List "Documents"

8.2 Verify Webhook Calls in Logs

Use logging in your webhook receiver to track calls:

Start-Transcript -Path "C:\Logs\WebhookLog.txt" -Append

8.3 Renew Expired Webhooks Automatically

Schedule this script via Windows Task Scheduler:

$subscriptions = Get-PnPWebhookSubscription -List "Documents"
foreach ($subscription in $subscriptions) {
    $expiry = [datetime]$subscription.ExpirationDateTime
    if ($expiry -lt (Get-Date).AddDays(5)) {
        Update-PnPWebhookSubscription -List "Documents" -Identity $subscription.Id -ExpirationDate (Get-Date).AddMonths(6)
    }
}

Result: Webhooks are auto-renewed.