Webhook Payload

Webhook Integration

TAMradar uses webhooks to deliver real-time notifications about changes detected by your radars. By configuring a webhook URL, you'll receive instant updates whenever relevant data is found.

Setting Up Your Webhook Endpoint

1. Create an HTTPS endpoint on your server that can receive POST requests
2. Configure your radar with this webhook URL
3. Ensure your endpoint returns a 2xx status code to acknowledge receipt

Webhook Payload Format

All webhook payloads follow this structure:

JSON

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_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",
		"next_charge_at": "2024-04-20T12:30:00Z",
    "custom_fields": {
      "priority": "high",
      "target_account_id": "0011U00000TFV7MQAX"
    }
  },
  "content": {
    // Event-specific data
  }
}

Base Fields

Field	Type	Required	Description
event_id	string	Yes	Unique identifier for this webhook event
event_type	string	Yes	Type of event (see Event Types below)
record_id	string|null	Yes	Unique identifier for the detected record (null for failures)
discovered_at	string	Yes	ISO timestamp (UTC) when the update was detected

Event Types

Event Type	Description
radar_finding	New data detected by a radar (default)
radar_failure	Radar setup failed and balance used was refunded

Radar Types

Radar Type	Description
company_mentions	Social media and article mentions of a company
company_social_posts	Social media posts from company
company_social_posts_cxo	Social media posts from company executives
job_openings	New job postings
new_hires	New employee detections & hirings
promotions	Employee promotions and role changes
reviews	Customer reviews across platforms
contact_job_changes	Individual contact career changes (departures, promotions, role changes)

Radar Failure Notifications

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

JSON

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "radar_failure",
  "record_id": null,
  "discovered_at": "2024-03-20T12:30:00Z",
  "data": {
    "radar_id": "54e32291-25a4-459f-8bd6-4f79489ea931",
    "radar_type": "company_social_posts", 
    "domain": "example.com",
		"next_charge_at": null,
    "custom_fields": {
      "priority": "high"
    }
  },
  "content": {
    "failure_reason": "missing_prerequisites",
    "refund_amount_usd": 0.15,
    "message": "Radar creation failed: missing prerequisites."
  }
}

Failure Reasons

Reason	Description	Action
missing_prerequisites	Required accounts or data sources not found	Verify the company has public profiles that can be monitored
insufficient_funds	User has insufficient balance for radar creation	Add credits to account and retry
setup_failure	Generic failure during radar creation/initialisation	Contact support for assistance

Best Practices for Webhook Handling

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

Testing Your Webhook

1. Inspect the JSON-Schema (recommended)

Fetch the full JSON-Schema we use in production:

cURL

curl --location 'https://api.tamradar.com/v1/webhooks/schema' \
--header 'x-api-key: YOUR_API_KEY'

2. Trigger a sample delivery

Use the /v1/webhooks/test helper to generate – and optionally send – a payload that matches the schema.

Required: radar_type

Optional:
event_type (radar_finding default, or radar_failure) webhook_url – if provided, we POST the payload to your URL; if omitted, we just return it in the response.

cURL

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"
  }'

The response looks like:

JSON

{
  "status": "success",
  "code": 200,
  "payload": { ... }   // The exact JSON sent (or that would be sent) to your webhook
}

No retries or signatures are applied in test mode.

Need help? Contact our team