Webhook Payloads - TAMradar API Docs

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.

Payload Libraries by Category

Company Payloads

Contact Payloads

Industry Payloads

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-a8b9-4c0d-b1e2-f3a4b5c6d7e8",

  "discovered_at": "2024-03-20T12:30:00Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
    "radar_type": "company_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 or billing failure (may include refund metadata)
`radar_created`	Async bulk item was created successfully
`bulk_completed`	Async bulk request finished processing all items

Per-item bulk webhook events

Before the final bulk_completed, each item delivers its own webhook as it finishes:

radar_created — item was created successfully. Includes code: 201, message: "Radar created successfully", completed_at, and a full data block matching the single-radar creation response.
radar_failure — item failed validation, conflict, or billing. Includes completed_at, code, errors[], and message matching the sync API error shape. Also emits discovered_at (same value as completed_at) for backwards compatibility — prefer completed_at going forward.

radar_created example:

{
  "update_id": "efbf7c77-c1ae-4a0d-85b6-116674e9e0b1",
  "update_type": "radar_created",
  "record_id": null,
  "code": 201,
  "message": "Radar created successfully",
  "completed_at": "2026-05-25T11:17:20Z",
  "bulk_id": "5f9da22e-4778-427c-b7e4-dab2a8d9d709",
  "item_index": 0,
  "custom_fields": { "crm_account_id": "acc_001" },
  "status": "success",
  "data": {
    "radar_id": "2ffb1a07-ac95-4a6d-bc34-39f479f1c856",
    "radar_type": "company_job_openings",
    "domain": "stripe.com",
    "radar_status": "active",
    "webhook_url": "https://your-domain.com/webhooks/tamradar",
    "created_at": "2026-05-25T11:17:18Z",
    "deactivated_at": null,
    "next_charge_at": "2026-06-25T11:17:18Z",
    "custom_fields": { "crm_account_id": "acc_001" }
  }
}

radar_failure example:

{
  "update_id": "a1b2c3d4-0001-4000-b000-000000000001",
  "update_type": "radar_failure",
  "record_id": null,
  "completed_at": "2026-05-25T11:17:26Z",
  "discovered_at": "2026-05-25T11:17:26Z",
  "bulk_id": "5f9da22e-4778-427c-b7e4-dab2a8d9d709",
  "item_index": 1,
  "custom_fields": {},
  "status": "error",
  "code": 409,
  "message": "Conflict: Radar already exists",
  "errors": [
    {
      "field": "domain",
      "reason": "A radar with this domain and type already exists for your account. Conflicting radar_id: 3f1d8e8a-39c4-47e8-a4b4-f7db6a2e50f0. You can view it using GET /radars/{radar_id}",
      "conflicting_radar_id": "3f1d8e8a-39c4-47e8-a4b4-f7db6a2e50f0"
    }
  ],
  "refund_amount_usd": 0,
  "error_id": "45ed35e5-986c-4496-afd8-9a84f6baa410",
  "timestamp": "2026-05-25T11:17:26.000Z"
}

Bulk `update_id` semantics

For bulk_completed events, two ID levels can appear and they serve different purposes:

Top-level update_id: idempotency key for the whole bulk_completed webhook event.
Per-item radars[].update_id: correlation key for each item’s earlier radar_created or radar_failure event.

Store both when you consume bulk webhooks:

Deduplicate bulk_completed retries by top-level update_id.
Correlate each radars[] item back to its individual item event with radars[].update_id.

bulk_completed payloads use a batch envelope with completed_at, summary, and radars[]. Each entry in radars[] is the verbatim payload from that item’s per-item webhook:

{
  "update_id": "9a2f0f77-5c8b-4b3e-b636-3ad539f4de65",
  "update_type": "bulk_completed",
  "bulk_id": "5f9da22e-4778-427c-b7e4-dab2a8d9d709",
  "completed_at": "2026-05-25T11:17:33Z",
  "summary": {
    "total": 3,
    "created": 2,
    "failed": 1
  },
  "radars": [
    {
      "update_id": "efbf7c77-c1ae-4a0d-85b6-116674e9e0b1",
      "update_type": "radar_created",
      "code": 201,
      "message": "Radar created successfully",
      "completed_at": "2026-05-25T11:17:20Z",
      "bulk_id": "5f9da22e-4778-427c-b7e4-dab2a8d9d709",
      "item_index": 0,
      "custom_fields": { "crm_account_id": "acc_001" },
      "status": "success",
      "data": { "radar_id": "2ffb1a07-ac95-4a6d-bc34-39f479f1c856" }
    },
    {
      "update_id": "a1b2c3d4-0001-4000-b000-000000000001",
      "update_type": "radar_failure",
      "record_id": null,
      "completed_at": "2026-05-25T11:17:26Z",
      "discovered_at": "2026-05-25T11:17:26Z",
      "bulk_id": "5f9da22e-4778-427c-b7e4-dab2a8d9d709",
      "item_index": 1,
      "custom_fields": {},
      "status": "error",
      "code": 409,
      "message": "Conflict: Radar already exists",
      "errors": [
        {
          "field": "domain",
          "reason": "A radar with this domain and type already exists for your account. Conflicting radar_id: 3f1d8e8a-39c4-47e8-a4b4-f7db6a2e50f0.",
          "conflicting_radar_id": "3f1d8e8a-39c4-47e8-a4b4-f7db6a2e50f0"
        }
      ],
      "refund_amount_usd": 0,
      "error_id": "45ed35e5-986c-4496-afd8-9a84f6baa410",
      "timestamp": "2026-05-25T11:17:26Z"
    }
  ]
}

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 Failure Notifications

When a radar fails setup or is deactivated due to billing, you’ll receive a radar_failure notification:

{
  "update_id": "550e8400-e29b-41d4-a716-446655440000",
  "update_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2024-03-20T12:30:00Z",
  "completed_at": "2024-03-20T12:30:00Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
    "radar_type": "company_job_openings",
    "domain": "example.com",
    "custom_fields": {
      "priority": "high"
    }
  },
  "status": "error",
  "code": 402,
  "message": "Radar was deactivated due to insufficient credits.",
  "errors": [{ "field": "radar", "reason": "insufficient_funds" }],
  "refund_amount_usd": 0,
  "timestamp": "2024-03-20T12:30:00Z",
  "error_id": "550e8400-e29b-41d4-a716-446655440000"
}

When setup fails, the same radar_failure shape is used with a different code and refund value:

{
  "update_id": "550e8400-e29b-41d4-a716-446655440001",
  "update_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2024-03-20T12:30:00Z",
  "completed_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"
    }
  },
  "status": "error",
  "code": 400,
  "message": "Radar creation failed because the domain does not have required social media accounts.",
  "errors": [{ "field": "radar", "reason": "missing_prerequisites" }],
  "refund_amount_usd": 0.10,
  "timestamp": "2024-03-20T12:30:00Z",
  "error_id": "550e8400-e29b-41d4-a716-446655440001"
}

Failure Reasons

Identify the failure type from code and message. The errors[].reason field contains the machine-readable reason key.

`code`	`errors[].reason`	Description
`400`	`missing_prerequisites`	Required accounts or data sources not found
`400`	`setup_failure`	General setup failure during radar initialization
`400`	`source_inaccessible`	Target source (e.g. LinkedIn profile, domain) is inaccessible or private
`402`	`insufficient_funds`	Radar deactivated — balance too low to cover the charge

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 Failure Events: Monitor radar_failure to handle billing/setup problems quickly
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": "company_job_openings"    // any supported radar_type
    // "update_type": "radar_failure"        // optional, defaults to radar_finding
  }'

The test event is fire-and-forget, with no retries or signatures, and uses the same payload format you’ll receive in production. Need help? Contact our team

​How TAMradar delivers updates

​Payload Libraries by Category

​Company Payloads

​Contact Payloads

​Industry Payloads

​Setting Up Webhook Delivery (optional)

​Webhook Payload Format

​Base Fields

​Update Types

​Per-item bulk webhook events

​Bulk update_id semantics

​Radar Types

​Radar Failure Notifications

​Failure Reasons

​Best Practices for Webhook Handling

​Testing Your Webhook

​Quick test