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:

// 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

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.

{
  "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.

{
  "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.

{
  "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:

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: [e-mail]

• 📚 Documentation: docs.aidp.dev/webhooks