Update Payloads

How TAMradar delivers updates

TAMradar supports two ways to receive radar findings:

Webhooks (push) — TAMradar POSTs events to your webhook_url in real-time. Set webhook_url when creating a radar to enable this.
Polling (pull) — Fetch findings on demand via GET /v1/updates. Works for all radars, including those created without a webhook_url.

Both delivery methods use the same payload format documented below.

Setting Up Webhook Delivery (optional)

If you want real-time push delivery, set up an HTTPS endpoint:

Create an HTTPS endpoint on your server that can receive POST requests
Pass webhook_url when creating your radar
Ensure your endpoint returns a 2xx status code to acknowledge receipt

No webhook? Skip webhook_url entirely to create a poll-only radar. Findings are always available via GET /v1/updates regardless.

Webhook Payload Format

All webhook payloads follow this structure:

{
  "update_id": "550e8400-e29b-41d4-a716-446655440000",
  "update_type": "radar_finding",
  "record_id": "c4d5e6f7-g8h9-4i0j-k1l2-m3n4o5p6q7r8",

  "discovered_at": "2024-03-20T12:30:00Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
    "radar_type": "job_openings",
    "domain": "example.com",
    "custom_fields": {
      "priority": "high",
      "target_account_id": "0011U00000TFV7MQAX"
    }
  },
  "content": {
    // Event-specific data
  }
}

Base Fields

Field	Type	Required	Description
update_id	string	Yes	Unique identifier for this webhook update
update_type	string	Yes	Type of update (see Update Types below)
record_id	string	No	Unique identifier for the detected record
radar_type	string	Yes	Type of radar that generated the event
discovered_at	string	Yes	ISO timestamp (UTC) when the update was detected

Update Types

Update Type	Description
`radar_finding`	New data detected by a radar (default)
`radar_failure`	Radar setup failed and credits were refunded

Radar Types

Radar Type	Description
`company_mentions`	Social media and article mentions of your company
`company_social_posts`	Company's own social media activity
`company_social_posts_cxo`	Social media posts from company executives
`company_social_engagements`	Social media engagements (likes, comments) on company posts
`company_job_openings`	New job postings from tracked companies
`company_new_hires`	New employee detections
`company_promotions`	Employee promotions and role changes
`company_reviews`	Customer reviews across platforms
`contact_job_changes`	Individual contact career changes (departures, promotions, role changes)
`contact_social_posts`	Social media posts from tracked contacts
`contact_social_engagements`	Social media engagements (likes, comments) by tracked contacts
`industry_mentions`	Industry-wide mentions and news articles
`industry_funding_rounds`	Funding rounds across companies in your industry
`industry_job_openings`	Job openings across companies in your industry
`industry_new_companies`	New companies emerging in your industry

Radar Status Updates

When a radar's status changes, you'll receive a notification:

{
  "update_id": "550e8400-e29b-41d4-a716-446655440000",
  "update_type": "radar_failure",
  "discovered_at": "2024-03-20T12:30:00Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
     "radar_type": "job_openings",
    "domain": "example.com",
    "custom_fields": {
      "priority": "high"
    }
  },
  "content": {
    "failure_reason": "insufficient_funds",
    "refund_amount": 0,
    "message": "Radar was deactivated due to insufficient credits."
  }
}

Status Change Reasons

Reason	Description
`user_deactivated`	User requested deactivation (grace period applies)
`insufficient_funds`	Account ran out of credits
`grace_period_ended`	Radar completed its grace period
`system_deactivated`	System-initiated deactivation

Radar Failure Notifications

When a radar setup fails, you'll receive a notification with refund details:

{
  "update_id": "550e8400-e29b-41d4-a716-446655440000",
  "update_type": "radar_failure",
  "discovered_at": "2024-03-20T12:30:00Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
    "radar_type": "company_social_posts",
    "domain": "example.com",
    "custom_fields": {
      "priority": "high"
    }
  },
  "content": {
    "failure_reason": "missing_prerequisites",
    "refund_amount": 100,
    "message": "Radar creation failed because the domain does not have required social media accounts."
  }
}

Failure Reasons

Reason	Description
`missing_prerequisites`	Required accounts or data sources not found
`setup_failure`	General setup failure
`insufficient_funds`	Radar deactivated due to insufficient credits
`source_inaccessible`	Target source (e.g. LinkedIn profile, domain) is inaccessible or private

Best Practices for Webhook Handling

Respond Quickly: Return a 2xx status code immediately, then process asynchronously
Implement Retry Logic: Be prepared to handle the same event multiple times
Verify Signatures: Check webhook signatures to validate authenticity (documentation coming soon)
Track Status Changes: Monitor status updates to understand radar lifecycle
Handle Null Fields: Some fields like record_id may be null for certain event types

Testing Your Webhook

Quick test

Trigger a sample payload to your endpoint:

curl -X POST https://api.tamradar.com/v1/webhooks/test \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-domain.com/webhook",
    "radar_type": "job_openings"            // any supported radar_type
    // "update_type": "radar_failure"        // optional, defaults to radar_finding
  }'

The test event is fire-and-forget—no retries or signatures—and uses the same payload format you'll receive in production.

Need help? Contact our team