> ## Documentation Index
> Fetch the complete documentation index at: https://docs.statusstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Integration

> Custom integrations via webhooks

## Overview

Webhooks allow you to integrate StatusStack with any service that accepts HTTP webhooks, including PagerDuty, Datadog, custom systems, and more.

***

## Setup Guide

<Steps>
  <Step title="Get Webhook URL">
    From your target service:

    * PagerDuty: Events API v2 endpoint
    * Datadog: Webhook integration URL
    * Custom: Your webhook endpoint
  </Step>

  <Step title="Configure in StatusStack">
    1. **Settings** → **Notifications**
    2. Create rule
    3. Select **Webhook** channel
    4. Enter webhook URL
    5. Add custom headers (optional)
    6. Select HTTP method (POST default)
  </Step>

  <Step title="Test">
    Send test webhook
  </Step>
</Steps>

***

## Webhook Payload

StatusStack sends JSON payloads:

```json theme={null}
{
  "event": "component.status_changed",
  "timestamp": "2025-01-19T10:30:00Z",
  "stack": {
    "id": "stack_abc123",
    "name": "Production Infrastructure",
    "slug": "production"
  },
  "component": {
    "id": "comp_xyz789",
    "name": "Production API",
    "previous_status": "operational",
    "current_status": "critical"
  },
  "incident": {
    "id": "inc_123",
    "created_at": "2025-01-19T10:30:00Z"
  }
}
```

***

## Security

### Webhook Signatures

StatusStack signs webhooks with HMAC-SHA256:

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}
```

Signature sent in `X-StatusStack-Signature` header.

***

## Common Integrations

### PagerDuty

```yaml theme={null}
Webhook URL: https://events.pagerduty.com/v2/enqueue
Headers:
  Authorization: Token token=your-integration-key
  Content-Type: application/json

Payload mapping:
  - event_action: trigger/acknowledge/resolve
  - severity: critical/error/warning/info
  - summary: Component status message
```

### Datadog

```yaml theme={null}
Webhook URL: https://api.datadoghq.com/api/v1/events
Headers:
  DD-API-KEY: your-api-key
  Content-Type: application/json
```

### Custom Endpoint

```javascript theme={null}
// Your webhook receiver
app.post('/webhooks/statusstack', (req, res) => {
  const { event, stack, component } = req.body;
  
  // Verify signature
  if (!verifyWebhook(req.body, req.headers['x-statusstack-signature'])) {
    return res.status(401).send('Invalid signature');
  }
  
  // Handle event
  if (event === 'component.status_changed') {
    // Create alert in your system
    createAlert(component);
  }
  
  res.status(200).send('OK');
});
```

***

## Event Types

StatusStack sends these event types:

* `component.status_changed`
* `monitor.down`
* `monitor.recovered`
* `incident.created`
* `incident.updated`
* `incident.resolved`
* `maintenance.scheduled`

Filter events in notification rule settings.

***

## Best Practices

* **Verify signatures** to prevent spoofing
* **Return 200 OK** quickly (\< 5 seconds)
* **Process asynchronously** for heavy operations
* **Handle retries** gracefully (idempotent)
* **Log failures** for debugging

***

## Troubleshooting

### Webhook Failing

**Check:**

1. URL is publicly accessible (HTTPS required)
2. Endpoint returns 200 OK
3. No firewall blocking StatusStack IPs
4. Signature verification (if enabled)

### Delayed Delivery

**Causes:**

* Your endpoint is slow (> 5 seconds)
* Rate limiting
* Network issues

**Solutions:**

* Return 200 immediately, process async
* Increase timeout settings
* Check endpoint logs

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Notification Setup" icon="bell" href="/guides/notification-setup">
    Configure notification rules
  </Card>
</CardGroup>