Add incident notifications guide for Slack and PagerDuty (GTM-2216)

credible/dapp-incidents.mdx

@@ -5,6 +5,22 @@ description: 'View incidents prevented by the Credible Layer'
 
 Incidents show when transactions were dropped because they violated assertions protecting contracts. This happens when a transaction that interacted with an assertion-protected contract was dropped by the [Enforcer](/credible/glossary#assertion-enforcer) because it caused an assertion to revert.
 
+## How Incidents Are Grouped
+
+An incident represents the invalidation of an assertion over a one-hour time period. Multiple dropped transactions can belong to the same incident if they violate the same assertion within that window.
+
+**Why group transactions into incidents?**
+
+- An attacker may craft multiple transactions that all violate the same assertion—these represent the same logical attack
+- One hour is a reasonable estimate for how long an attack attempt might last
+- After one hour without violations, a new invalidation likely indicates a different attack and creates a new incident
+
+This grouping ensures you receive meaningful alerts without being spammed by repeated notifications for the same security event.
+
+<Note>
+This is our initial approach to incident grouping and may be refined based on user feedback.
+</Note>
+
 ## Incidents View
 
 Access incidents from the **Incidents** tab in the dApp navigation bar. This shows a limited view of all incidents across all networks:
@@ -57,9 +73,7 @@ You can also set up external alerts via webhooks:
 - **Slack Integration**: Configure Slack webhooks to receive incident notifications in your Slack channels
 - **PagerDuty Integration**: Configure PagerDuty webhooks to receive incident notifications
 
-<Note>
-Detailed setup instructions for Slack and PagerDuty integrations will be available in a dedicated documentation page.
-</Note>
+See [Integrations](/credible/dapp-integrations) for setup instructions.
 
 ## Use Cases
 

credible/dapp-integrations.mdx

@@ -0,0 +1,163 @@
+---
+title: 'Incident Notifications'
+description: 'Configure Slack and PagerDuty to receive real-time incident notifications'
+---
+
+Set up Slack and PagerDuty integrations to receive notifications when [assertion incidents](/credible/dapp-incidents) occur in your Credible Layer projects.
+
+## Accessing Integration Settings
+
+1. Navigate to your project in the Credible Layer dashboard
+2. Go to **Settings** in the navigation bar
+3. Select **Slack** or **PagerDuty** from the "Integrations" section
+
+<Frame caption="Adding Notification Integration">
+  <img src="/images/add-notification-integration-credible-dapp.webp" alt="Adding Notification Integration" />
+</Frame>
+
+## Slack Integration
+
+The Slack integration sends formatted incident notifications to a channel of your choice using Slack's Incoming Webhooks.
+
+<Steps>
+<Step title="Create a Slack App">
+1. In the Credible Layer Settings page, click **Create a Slack App**
+2. This opens Slack's app creation page with a pre-filled manifest. No manual configuration needed
+3. Select the workspace where you want to receive notifications
+4. Click **Create**
+</Step>
+
+<Step title="Enable Incoming Webhooks">
+1. In your newly created Slack app, go to **Features → Incoming Webhooks**
+2. Toggle **Activate Incoming Webhooks** to **On**
+3. Click **Add New Webhook to Workspace**
+4. Select the channel where you want incident notifications
+5. Click **Allow**
+</Step>
+
+<Step title="Copy the Webhook URL">
+After authorizing, you'll see your new webhook URL:
+
+```
+https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
+```
+
+Copy this URL.
+</Step>
+
+<Step title="Configure in Credible Layer">
+1. Return to Credible Layer Settings → Slack tab
+2. Paste your webhook URL in the input field
+3. Click **Save**
+</Step>
+
+<Step title="Test the Integration">
+1. After saving, click **Send Test Notification**
+2. Verify the message arrives in your selected Slack channel
+</Step>
+</Steps>
+
+## PagerDuty Integration
+
+The PagerDuty integration creates incidents in PagerDuty when assertion violations occur, using the Events API v2.
+
+<Steps>
+<Step title="Create a PagerDuty Service Integration">
+1. In PagerDuty, navigate to **Services → Service Directory**
+2. Select an existing service or create a new one
+3. Go to the **Integrations** tab
+4. Click **Add Integration**
+5. Search for and select **Events API v2**
+6. Click **Add**
+</Step>
+
+<Step title="Get the Integration Key">
+After adding the integration, you'll see the **Integration Key** (also called Routing Key). This is a 32-character alphanumeric string. Copy this key.
+
+<Tip>
+Click the **PagerDuty Integration Guide** button in the Credible Layer Settings page for direct access to PagerDuty's official documentation.
+</Tip>
+</Step>
+
+<Step title="Configure in Credible Layer">
+1. Go to Credible Layer Settings → PagerDuty tab
+2. Paste your 32-character routing key in the input field
+3. Click **Save**
+</Step>
+
+<Step title="Test the Integration">
+1. After saving, click **Send Test Notification**
+2. Verify the incident appears in your PagerDuty service
+</Step>
+</Steps>
+
+## What Gets Notified
+
+Both integrations send notifications when [assertion incidents](/credible/dapp-incidents) occur. Notifications include:
+
+- Project name and affected contract
+- Network/chain information
+- Transaction details (hash, block number)
+- Assertion violation reason
+- Direct link to view the incident in the dashboard
+
+## How Incidents Are Grouped
+
+You receive one notification per incident, not per transaction. An incident is defined as an assertion being invalidated within a one-hour time window.
+
+If an attacker crafts multiple transactions that all violate the same assertion, these are grouped into a single incident since they represent the same logical attack. After one hour without violations, a new invalidation creates a new incident.
+
+This prevents notification spam while ensuring you're alerted to distinct security events. See [Incidents](/credible/dapp-incidents#how-incidents-are-grouped) for more details.
+
+<Note>
+This grouping logic is our initial approach and may be refined based on user feedback.
+</Note>
+
+## Managing Integrations
+
+### Updating a Webhook or Key
+
+Paste a new URL or key and click **Save**. The old configuration is replaced.
+
+### Removing an Integration
+
+1. Scroll to the bottom of the integration card
+2. Click **Remove Integration**
+3. Confirm the removal
+
+<Note>
+Removing an integration stops all notifications but does not delete historical data. You can reconfigure at any time.
+</Note>
+
+## Troubleshooting
+
+| Issue | Solution |
+| --- | --- |
+| Slack webhook URL rejected | Ensure the URL starts with `https://hooks.slack.com/services/` |
+| PagerDuty key rejected | Verify the key is exactly 32 alphanumeric characters |
+| Test notification not received | Check that the integration is correctly configured in Slack/PagerDuty |
+| No notifications on incidents | Verify the integration shows as "configured" in Settings |
+
+## Security
+
+- Webhook URLs and routing keys are stored securely and never displayed in full after saving
+- Only project managers can configure integrations
+- Test notifications are rate-limited to prevent abuse
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Incidents" icon="warning" href="/credible/dapp-incidents">
+    Learn about incident monitoring
+  </Card>
+  <Card title="Projects" icon="folder" href="/credible/dapp-projects">
+    Manage your projects
+  </Card>
+  <Card title="dApp Overview" icon="info" href="/credible/dapp-overview">
+    Explore the full dApp
+  </Card>
+  <Card title="Writing Assertions" icon="code" href="/credible/write-first-assertion">
+    Create assertions for your contracts
+  </Card>
+</CardGroup>
+

credible/glossary.mdx

@@ -159,6 +159,11 @@ The transparent and public nature of all assertions deployed on PCL. Since asser
 
 ## Prevention
 
+### Incident
+A security event representing the invalidation of an assertion over a one-hour time period. Multiple dropped transactions can belong to the same incident if they violate the same assertion within that window. This grouping treats repeated attempts to exploit the same vulnerability as a single logical attack.
+
+Learn more: [Incidents](/credible/dapp-incidents)
+
 ### Revert
 What happens at the EVM/Solidity level when an assertion function detects that a transaction violates the rules defined in the assertion. When an assertion reverts, it signals that the transaction would result in an undesired state. The sidecar detects this revert and notifies the sequencer that the transaction should be dropped.
 

docs.json

@@ -72,6 +72,7 @@
               "credible/invariant-to-assertion",
               "credible/store-submit-assertions",
               "credible/deploy-assertions-dapp",
+              "credible/dapp-integrations",
               "credible/accelerate-with-ai"
             ]
           },