Webhooks Overview

Your App                    Ranked AI
   |                           |
   |  POST /api/v1/webhooks    |
   |  (subscribe to events)    |
   |-------------------------->|
   |                           |
   |                           |  keyword positions update
   |                           |  ----------------------->
   |   POST https://your.app   |
   |   (event payload)         |
   |<--------------------------|
   |                           |
   |   200 OK                  |
   |-------------------------->|

curl -X POST https://app.ranked.ai/api/v1/webhooks \
  -H "Authorization: Bearer rk_live_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Dashboard",
    "url": "https://your-app.com/webhooks/ranked",
    "project_id": "your-project-uuid",
    "events": ["keywords.updated", "content.status_changed", "audit.completed"]
  }'

app.post('/webhooks/ranked', (req, res) => {
  const event = req.body;

  switch (event.event) {
    case 'keywords.updated':
      // Sync latest keyword positions
      syncKeywords(event.project_id, event.data.keywords_updated);
      break;
    case 'content.status_changed':
      // Update content tracker
      updateContent(event.data.content_id, event.data.new_status);
      break;
    case 'audit.completed':
      // Pull latest audit results
      fetchAuditResults(event.data.audit_id);
      break;
  }

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

{
  "event": "keywords.updated",
  "timestamp": "2026-05-16T00:10:17.701Z",
  "project_id": "40596405-c27c-4dfc-89e4-142c87846d66",
  "data": {
    "keywords_updated": 20,
    "job_id": "abc-123"
  }
}