fix: improvements

docs/providers/documentation/pagerduty-provider.mdx

@@ -1,12 +1,16 @@
 ---
 title: "Pagerduty Provider"
-description: "Pagerduty Provider is a provider that allows to create incidents or post events to Pagerduty."
+description: "Pagerduty Provider allows integration with PagerDuty to create, manage, and synchronize incidents and alerts within Keep."
 ---
 
+## Description
+
+The Pagerduty Provider enables integration with PagerDuty to create, manage, and synchronize incidents and alerts within Keep. It supports both direct API key authentication and OAuth2, allowing greater flexibility for secure integration.
+
 ## Inputs
 
 - `title`: str: Title of the alert or incident.
-- `alert_body`: str: UTF-8 string of custom message for alert. Shown in incident body for events, and in the body for incidents.
+- `alert_body`: dict: https://developer.pagerduty.com/api-reference/a7d81b0e9200f-create-an-incident#request-body
 - `dedup`: str | None: Any string, max 255 characters, used to deduplicate alerts for events.
 - `service_id`: str: ID of the service for incidents.
 - `body`: dict: Body of the incident.
@@ -15,39 +19,66 @@ description: "Pagerduty Provider is a provider that allows to create incidents o
 
 ## Authentication Parameters
 
-The `api_key` or `routing_key` are required for connecting to the Pagerduty provider. You can obtain them as described in the "Connecting with the Provider" section.
+PagerDuty supports two authentication methods:
 
-Routing key, which is an integration or ruleset key. API key, which is a user or team API key.
+1. **API Key** - A user or team key, accessible through **Configuration > API Access** in PagerDuty.
+2. **OAuth2** - Supports installation with OAuth2, with access and refresh tokens managed within Keep.
 
 ## Connecting with the Provider
 
-To use the PagerdutyProvider, you'll need to provide either a routing_key or an api_key.
+To connect Keep to PagerDuty:
+
+- **Routing Key**: Use for event posting via the PagerDuty Events API.
+- **API Key**: Use for incident creation and management through the PagerDuty Incidents API.
+- **OAuth2**: Token management handled automatically by Keep.
+
+<Frame>
+  <img src="/images/connect-to-pagerduty.png" />
+</Frame>
 
+<Note>
 You can find your integration key or routing key in the PagerDuty web app under **Configuration** > **Integrations**, and select the integration you want to use.
 You can find your API key in the PagerDuty web app under **Configuration** > **API Access**.
 
-The routing_key is used to post events to Pagerduty using the events API.
+The routing_key is used to post events to PagerDuty using the events API.
 The api_key is used to create incidents using the incidents API.
 
+</Note>
+
+## PagerDuty Webhook Integration
+
+By default, when Keep installs itself as a webhook integration, it subscribes to all incident events ("Account Scope").
+
+<Frame>
+  <img src="/images/pagerduty-account-scope.png" />
+</Frame>
+
+If you wish to limit Keep to some specific services, you can do so by selecting the **Service** scope and selecting the services you want to subscribe to.
+
+<Frame>
+  <img src="/images/pagerduty-service-scope.png" />
+</Frame>
+
+Find this page under **Integrations** > **Generic Webhooks (v3)**
+
 ## Scopes
 
 Certain scopes may be required to perform specific actions or queries via the Pagerduty Provider. Below is a summary of relevant scopes and their use cases:
 
 - incidents_read (Incidents Read)
-    Required: True
-    Description: View incidents.
+  Required: True
+  Description: View incidents.
 - incidents_write (Incidents Write)
-    Required: False
-    Description: Write incidents.
+  Required: False
+  Description: Write incidents.
 - webhook_subscriptions_read (Webhook Subscriptions Read)
-    Required: False
-    Description: View webhook subscriptions.
-    (*Required for auto-webhook integration)
+  Required: False
+  Description: View webhook subscriptions.
+  (\*Required for auto-webhook integration)
 - webhook_subscriptions_write (Webhook Subscriptions Write)
-    Required: False
-    Description: Write webhook subscriptions.
-    (*Required for auto-webhook integration)
-
+  Required: False
+  Description: Write webhook subscriptions.
+  (\*Required for auto-webhook integration)
 
 ## Notes
 
@@ -59,6 +90,7 @@ An expired trial while using the free version of PagerDuty may result in the "pa
 
 The webhook integration adds Keep as a destination within the "Integrations" API within Pagerduty.
 This grants Keep access to the following scopes within Pagerduty:
+
 - `webhook_subscriptions_read`
 - `webhook_subscriptions_write`
 

keep-ui/app/providers/oauth2/[providerType]/page.tsx

@@ -16,6 +16,8 @@ export default async function InstallFromOAuth({
   const apiUrl = getApiURL();
   const cookieStore = cookies();
   const verifier = cookieStore.get("verifier");
+  const installWebhook = cookieStore.get("oauth2_install_webhook");
+  const pullingEnabled = cookieStore.get("oauth2_pulling_enabled");
 
   const response = await fetch(
     `${apiUrl}/providers/install/oauth2/${params.providerType}`,
@@ -29,6 +31,8 @@ export default async function InstallFromOAuth({
         ...searchParams,
         redirect_uri: `${process.env.NEXTAUTH_URL}/providers/oauth2/${params.providerType}`,
         verifier: verifier ? verifier.value : null,
+        install_webhook: installWebhook ? installWebhook.value : false,
+        pulling_enabled: pullingEnabled ? pullingEnabled.value : false,
       }),
       cache: "no-store",
     }

keep-ui/app/providers/provider-form.tsx

@@ -220,6 +220,8 @@ const ProviderForm = ({
     e.preventDefault();
     const verifier = generateRandomString();
     cookieCutter.set("verifier", verifier);
+    cookieCutter.set("oauth2_install_webhook", formValues.install_webhook);
+    cookieCutter.set("oauth2_pulling_enabled", formValues.pulling_enabled);
     const verifierChallenge = base64urlencode(await sha256(verifier));
 
     let oauth2Url = provider.oauth2_url;

keep/api/routes/providers.py

@@ -500,6 +500,8 @@ async def install_provider_oauth2(
     )
     try:
         provider_class = ProvidersFactory.get_provider_class(provider_type)
+        install_webhook = provider_info.pop("install_webhook", "true") == "true"
+        pulling_enabled = provider_info.pop("pulling_enabled", "true") == "true"
         provider_info = provider_class.oauth2_logic(**provider_info)
         provider_name = provider_info.pop(
             "provider_name", f"{provider_unique_id}-oauth2"
@@ -533,9 +535,16 @@ async def install_provider_oauth2(
             installation_time=time.time(),
             configuration_key=secret_name,
             validatedScopes=validated_scopes,
+            pulling_enabled=pulling_enabled,
         )
         session.add(provider)
         session.commit()
+
+        if install_webhook:
+            install_provider_webhook(
+                provider_type, provider.id, authenticated_entity, session
+            )
+
         return JSONResponse(
             status_code=200,
             content={