---
title: "Webhooks"
description: "Webhook integration for TraceRTM events"
keywords: [webhooks, events, notifications, integration]
---

# Webhooks

Receive real-time notifications of TraceRTM events via webhooks.

## Overview

Webhooks allow you to receive HTTP callbacks when events occur in TraceRTM, such as:
- Item created/updated/deleted
- Links created/deleted
- Status changes
- Project updates

## Setting Up Webhooks

### Create Webhook

```python
from tracertm import TraceRTM

client = TraceRTM(api_key="rtm_live_abc123...")

webhook = client.webhooks.create(
    url="https://your-app.com/webhooks/tracertm",
    events=["item.created", "item.updated", "link.created"],
    secret="your-webhook-secret"
)
```

### Using API

```bash
curl -X POST "https://api.tracertm.dev/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/tracertm",
    "events": ["item.created", "item.updated"],
    "secret": "your-secret"
  }'
```

## Webhook Events

### Available Events

- `item.created` - Item created
- `item.updated` - Item updated
- `item.deleted` - Item deleted
- `link.created` - Link created
- `link.deleted` - Link deleted
- `project.created` - Project created
- `project.updated` - Project updated

## Webhook Payload

### Example Payload

```json
{
  "event": "item.created",
  "timestamp": "2025-01-20T10:30:00Z",
  "data": {
    "id": "item_123",
    "title": "User Authentication",
    "view": "requirements",
    "status": "draft",
    "project_id": "proj_456"
  }
}
```

## Verifying Webhooks

### Signature Verification

```python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
```

## Handling Webhooks

### Express.js Example

```javascript
app.post('/webhooks/tracertm', (req, res) => {
  const signature = req.headers['x-tracertm-signature'];
  const payload = JSON.stringify(req.body);
  
  if (verifyWebhook(payload, signature, WEBHOOK_SECRET)) {
    // Process webhook
    handleEvent(req.body);
    res.status(200).send('OK');
  } else {
    res.status(401).send('Unauthorized');
  }
});
```

### Python Flask Example

```python
from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhooks/tracertm', methods=['POST'])
def webhook():
    signature = request.headers.get('X-TracertM-Signature')
    payload = request.get_data()
    
    if verify_webhook(payload, signature, WEBHOOK_SECRET):
        event = request.json
        handle_event(event)
        return 'OK', 200
    else:
        return 'Unauthorized', 401
```

## Related Documentation

- [Webhooks API](/docs/api-reference/rest-api/webhooks) - Complete webhook API reference
- [Event System](/docs/development/internals/event-system) - Event architecture
