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

# Webhooks

> Receive real-time event notifications via HTTP

Webhooks allow you to receive real-time notifications when events occur in your Kodo account.

## How It Works

1. You provide an endpoint URL
2. Kodo sends HTTP POST requests when events occur
3. Your server processes the events

## Webhook Payload

All webhooks include this structure:

```json theme={null}
{
  "event": "incident.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}
```

## Event Types

### Incident Events

```json theme={null}
{
  "event": "incident.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "uuid",
    "title": "Database connectivity issues",
    "status": "investigating",
    "severity": "major",
    "services": ["API", "Database"],
    "message": "We are investigating..."
  }
}
```

### Service Events

```json theme={null}
{
  "event": "service.status_changed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "uuid",
    "name": "API Gateway",
    "previous_status": "operational",
    "new_status": "degraded"
  }
}
```

### Monitor Events

```json theme={null}
{
  "event": "monitor.down",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "uuid",
    "name": "API Health Check",
    "url": "https://api.example.com/health",
    "error": "Connection timeout"
  }
}
```

## Verifying Webhooks

We sign all webhook requests with your signing secret. Verify the signature to ensure requests are from Kodo:

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

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-kodo-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  const { event, data } = req.body;
  // ...

  res.status(200).send('OK');
});
```

## Retry Policy

If your endpoint returns a non-2xx status code, we retry:

| Attempt   | Delay      |
| --------- | ---------- |
| 1st retry | 1 minute   |
| 2nd retry | 5 minutes  |
| 3rd retry | 30 minutes |
| 4th retry | 2 hours    |
| 5th retry | 24 hours   |

After 5 failed attempts, the webhook is disabled and you're notified.

## Best Practices

<AccordionGroup>
  <Accordion title="Respond quickly">
    Return a 2xx response immediately, then process asynchronously. We timeout after 30 seconds.
  </Accordion>

  <Accordion title="Handle duplicates">
    Use the event ID to deduplicate. Network issues may cause retries even on success.
  </Accordion>

  <Accordion title="Verify signatures">
    Always verify the webhook signature in production.
  </Accordion>

  <Accordion title="Use HTTPS">
    Webhook URLs must use HTTPS for security.
  </Accordion>
</AccordionGroup>

## Managing Webhooks via CLI

```bash theme={null}
# List webhooks
kodo webhooks list

# Create webhook
kodo webhooks create \
  --name "Deploy hook" \
  --url "https://example.com/webhook" \
  --events "incident.created,incident.resolved"

# View details and delivery history
kodo webhooks get WEBHOOK_ID

# Test a webhook
kodo webhooks test WEBHOOK_ID

# Activate/deactivate
kodo webhooks update WEBHOOK_ID --active
kodo webhooks update WEBHOOK_ID --inactive

# Delete
kodo webhooks delete WEBHOOK_ID --force
```

## Testing Webhooks

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    kodo webhooks test WEBHOOK_ID
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://kodostatus.com/api/v1/webhooks/WEBHOOK_ID/test" \
      -H "X-API-Key: your_api_key"
    ```
  </Tab>
</Tabs>

You can also use a service like [webhook.site](https://webhook.site) during development.