# Webhooks

Receive real-time notifications when events occur in your AIDP account.

## Overview

Webhooks allow your application to receive automated notifications when specific events happen, such as:

* New AI mentions of your business
* Profile updates
* Analytics milestones
* Customer interactions

***

## Setting Up Webhooks

### 1. Create an Endpoint

Create an HTTPS endpoint in your application to receive webhook events:

```javascript
// Express.js example
app.post('/webhooks/aidp', express.json(), (req, res) => {
  const event = req.body;

  // Verify webhook signature
  if (!verifySignature(req.headers['x-aidp-signature'], req.body)) {
    return res.status(401).send('Invalid signature');
  }

  // Handle event
  switch (event.type) {
    case 'business.mentioned':
      handleMention(event.data);
      break;
    case 'analytics.milestone':
      handleMilestone(event.data);
      break;
  }

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

### 2. Register Your Webhook

Register your endpoint in the Developer Dashboard:

1. Go to [Developer Dashboard](https://platform.aidp.dev/developers)
2. Navigate to Webhooks
3. Click "Add Webhook"
4. Enter your endpoint URL
5. Select events to subscribe to
6. Save and copy your signing secret

***

## Available Events

### Business Events

**`business.mentioned`** Triggered when AI mentions your business.

```json
{
  "type": "business.mentioned",
  "id": "evt_abc123",
  "created": "2024-12-12T10:30:00Z",
  "data": {
    "businessId": "biz_xyz789",
    "platform": "claude",
    "query": "coffee shops in Portland",
    "mentioned": true,
    "cited": true
  }
}
```

**`business.profile_updated`** Triggered when profile is updated.

```json
{
  "type": "business.profile_updated",
  "id": "evt_def456",
  "created": "2024-12-12T11:00:00Z",
  "data": {
    "businessId": "biz_xyz789",
    "updatedFields": ["description", "hours"],
    "updatedBy": "user_abc123"
  }
}
```

### Analytics Events

**`analytics.milestone`** Triggered when reaching analytics milestones.

```json
{
  "type": "analytics.milestone",
  "id": "evt_ghi789",
  "created": "2024-12-12T12:00:00Z",
  "data": {
    "businessId": "biz_xyz789",
    "milestone": "1000_impressions",
    "value": 1000,
    "period": "all_time"
  }
}
```

***

## Security

### Verify Webhook Signatures

Always verify webhook signatures to ensure requests are from AIDP:

```javascript
const crypto = require('crypto');

function verifySignature(signature, payload) {
  const secret = process.env.AIDP_WEBHOOK_SECRET;
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return signature === `sha256=${digest}`;
}
```

### Best Practices

* Use HTTPS endpoints only
* Verify all webhook signatures
* Return 200 status quickly (process async)
* Implement retry logic for failures
* Log all webhook events

***

## Testing

Test webhooks using the Developer Dashboard:

1. Go to Webhooks section
2. Select your webhook
3. Click "Send Test Event"
4. Choose event type
5. Verify your endpoint receives it

***

## Need Help?

* 📧 Email: <webhooks@aidp.dev>
* 📚 Documentation: [docs.aidp.dev/webhooks](https://docs.aidp.dev/webhooks)