Webhooks

When a signal fires, Datamagnet sends an HTTP POST request to the webhook_url you configured when creating the signal.

Registering a webhook

Pass a webhook_url when calling /signal/create or update it later via /signal/update.

Example

{
  "signal_type": "keyword_engagement",
  "keywords": ["sales intelligence"],
  "webhook_url": "https://yourapp.com/webhooks/signals",
  "webhook_secret": "your-hmac-secret"
}

Payload format by signal type

job_change · new_post

job_change

{
  "signal_type": "job_change",
  "profile_url": "https://linkedin.com/in/satyanadella",
  "detected_at": "2024-01-16T09:14:32Z",
  "data": {
    "previous_company": "Microsoft",
    "previous_title": "CEO",
    "current_company": "OpenAI",
    "current_title": "Board Member",
    "profile_name": "Satya Nadella"
  }
}

new_post

{
  "signal_type": "new_post",
  "profile_url": "https://linkedin.com/in/reidhoffman",
  "detected_at": "2024-01-16T09:14:32Z",
  "data": {
    "post_url": "https://linkedin.com/posts/reidhoffman_activity-...",
    "post_text": "Excited to share our latest thinking on AI agents...",
    "published_at": "2024-01-16T08:55:00Z",
    "profile_name": "Reid Hoffman"
  }
}

Engagement signals

All four engagement signal types — keyword_engagement, industry_engagement, company_engagement, and person_engagement — share the same webhook payload structure. The only difference is the signal_type value and the meaning of signal_keyword.

keyword_engagement example

{
  "user_email": "user@example.com",
  "signal_type": "keyword_engagement",
  "run_stats": {
    "keywords_processed": 5,
    "total_raw": 142,
    "after_dedup": 89,
    "after_icp": 14,
    "flame_1": 4,
    "flame_2": 7,
    "flame_3": 3
  },
  "leads": [
    {
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "profile_name": "John Doe",
      "headline": "VP Sales at Acme Corp",
      "signal_keyword": "sales intelligence",
      "engagement_type": "comment",
      "engagement_post_url": "https://linkedin.com/posts/someauthor_activity-7123456789",
      "engagement_link": "https://linkedin.com/posts/someauthor_activity-7123456789?commentUrn=urn%3Ali%3Acomment%3A123",
      "comment_text": "This is exactly the problem we've been trying to solve. Would love to chat.",
      "post_excerpt": "Most sales teams are flying blind. Here's how the top 1% use intent data to close 3x faster...",
      "post_author": "Jane Smith",
      "lead_score": 3,
      "icp_score": 0.87,
      "signal_score": 0.91,
      "detected_at": "2026-04-20T09:15:00Z"
    },
    {
      "linkedin_url": "https://linkedin.com/in/janedoe",
      "profile_name": "Jane Doe",
      "headline": "CRO at TechCo",
      "signal_keyword": "outbound prospecting",
      "engagement_type": "like",
      "engagement_post_url": "https://linkedin.com/posts/someauthor_activity-9876543210",
      "engagement_link": "https://linkedin.com/posts/someauthor_activity-9876543210",
      "comment_text": null,
      "post_excerpt": "Cold outbound is not dead. Here's the 5-step framework we used to book 200 meetings last quarter...",
      "post_author": "Bob Jones",
      "lead_score": 2,
      "icp_score": 0.74,
      "signal_score": 0.68,
      "detected_at": "2026-04-20T09:15:00Z"
    }
  ]
}

company_engagement example

{
  "user_email": "user@example.com",
  "signal_type": "company_engagement",
  "run_stats": {
    "companies_processed": 3,
    "total_raw": 78,
    "after_dedup": 51,
    "after_icp": 9,
    "flame_1": 2,
    "flame_2": 5,
    "flame_3": 2
  },
  "leads": [
    {
      "linkedin_url": "https://linkedin.com/in/alexchen",
      "profile_name": "Alex Chen",
      "headline": "Director of Sales at StartupXYZ",
      "signal_keyword": "Salesforce",
      "engagement_type": "comment",
      "engagement_post_url": "https://linkedin.com/posts/salesforce_activity-1234567890",
      "engagement_link": "https://linkedin.com/posts/salesforce_activity-1234567890?commentUrn=urn%3Ali%3Acomment%3A456",
      "comment_text": "We switched from Salesforce last year and the ROI has been incredible.",
      "post_excerpt": "Announcing Salesforce Einstein AI — the future of CRM is here. Watch our keynote...",
      "post_author": "Salesforce",
      "lead_score": 3,
      "icp_score": 0.91,
      "signal_score": 0.88,
      "detected_at": "2026-04-20T09:15:00Z"
    }
  ]
}

industry_engagement example

{
  "user_email": "user@example.com",
  "signal_type": "industry_engagement",
  "run_stats": {
    "industries_processed": 2,
    "total_raw": 95,
    "after_dedup": 62,
    "after_icp": 11,
    "flame_1": 3,
    "flame_2": 6,
    "flame_3": 2
  },
  "leads": [
    {
      "linkedin_url": "https://linkedin.com/in/morganlee",
      "profile_name": "Morgan Lee",
      "headline": "VP of Revenue at FinTechCo",
      "signal_keyword": "Financial Services",
      "engagement_type": "like",
      "engagement_post_url": "https://linkedin.com/posts/fintech-author_activity-5678901234",
      "engagement_link": "https://linkedin.com/posts/fintech-author_activity-5678901234",
      "comment_text": null,
      "post_excerpt": "The fintech landscape in 2026: open banking is no longer optional for survival...",
      "post_author": "Sarah Williams",
      "lead_score": 2,
      "icp_score": 0.82,
      "signal_score": 0.65,
      "detected_at": "2026-04-20T09:15:00Z"
    }
  ]
}

person_engagement example

{
  "user_email": "user@example.com",
  "signal_type": "person_engagement",
  "run_stats": {
    "persons_processed": 2,
    "total_raw": 44,
    "after_dedup": 31,
    "after_icp": 7,
    "flame_1": 1,
    "flame_2": 4,
    "flame_3": 2
  },
  "leads": [
    {
      "linkedin_url": "https://linkedin.com/in/taylorwong",
      "profile_name": "Taylor Wong",
      "headline": "Head of Revenue Operations at ScaleUp Inc",
      "signal_keyword": "John Doe",
      "engagement_type": "comment",
      "engagement_post_url": "https://linkedin.com/posts/johndoe_activity-2345678901",
      "engagement_link": "https://linkedin.com/posts/johndoe_activity-2345678901?commentUrn=urn%3Ali%3Acomment%3A789",
      "comment_text": "Totally agree John — pipeline velocity is the metric nobody talks about but everyone should.",
      "post_excerpt": "After running sales teams for 10 years, here's the one metric I wish I'd tracked from day one...",
      "post_author": "John Doe",
      "lead_score": 3,
      "icp_score": 0.93,
      "signal_score": 0.95,
      "detected_at": "2026-04-20T09:15:00Z"
    }
  ]
}

Engagement signal payload fields

Top level

string

The account email that owns the signal.

string

One of "keyword_engagement" · "company_engagement" · "industry_engagement" · "person_engagement".

object

Aggregated counts for this run. The group count key varies by signal type:

Signal type	Group count key
`keyword_engagement`	`keywords_processed`
`industry_engagement`	`industries_processed`
`company_engagement`	`companies_processed`
`person_engagement`	`persons_processed`

All types include total_raw, after_dedup, after_icp, flame_1, flame_2, flame_3.

array

Qualified leads sorted by lead_score descending. Each object contains the fields below.

Per-lead fields

string

The LinkedIn profile URL of the person who engaged.

string

Full name of the engager.

string

Current LinkedIn headline of the engager.

string

The search term or group label that surfaced this lead.

keyword_engagement — the keyword that matched (e.g. "sales intelligence")
company_engagement — the company label (e.g. "Salesforce")
industry_engagement — the industry label (e.g. "Financial Services")
person_engagement — the monitored person’s label (e.g. "John Doe")

string

How the person engaged with the post. Either "like" (or a specific reaction type such as "celebrate", "support") or "comment".

string

URL of the LinkedIn post the person engaged with.

string

Deep link to the specific engagement. For comments, this links directly to the comment. For likes, same as engagement_post_url.

string | null

The text of the comment left by the engager. null for likes and reactions — only populated when engagement_type is "comment".

string | null

First 300 characters of the post the engager interacted with. Gives context about the content that triggered the signal. null if the post text could not be retrieved.

string | null

Full name of the person or page who authored the post. null if the author could not be retrieved.

integer

Overall lead quality score from 1 to 3.

Score	Threshold	Meaning
`3`	composite ≥ 0.75	High-fit, high-intent
`2`	composite ≥ 0.50	Good fit
`1`	composite < 0.50	Weak signal

composite = 0.5 × icp_score + 0.5 × signal_score

number

ICP fit score between 0.0 and 1.0. Reflects how well the lead matches the configured ICP filters.

number

Intent signal score between 0.0 and 1.0. Based on engagement type (comment = 1.0, like = 0.7), post recency (decays over 14 days), and keyword specificity.

string

ISO 8601 timestamp of when the lead was scored.

job_change · new_post payload fields

string

"job_change" or "new_post".

string

The LinkedIn profile URL that triggered the signal.

string

ISO 8601 timestamp of detection.

object

Signal-specific data.

Show job_change fields

string

Company before the change.

string

Title before the change.

string

New company.

string

New title.

string

Full name of the tracked person.

Show new_post fields

string

Direct URL to the post.

string

Post text content.

string

ISO 8601 publish timestamp.

string

Full name of the tracked person.

Verifying webhook signatures

If you set a webhook_secret, every request includes an X-Datamagnet-Signature header — an HMAC-SHA256 of the raw request body signed with your secret.

import hmac
import hashlib
from flask import request

def verify_signature(secret: str) -> bool:
    signature = request.headers.get("X-Datamagnet-Signature", "")
    body = request.get_data()
    expected = hmac.new(
        key=secret.encode("utf-8"),
        msg=body,
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

const crypto = require('crypto')

function verifySignature(secret, rawBody, signatureHeader) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  )
}

function verifySignature(string $secret, string $rawBody, string $signatureHeader): bool {
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}

Always use a timing-safe comparison (hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js) to prevent timing attacks.

Responding to webhooks

Your endpoint must return a 2xx status within 10 seconds. If it times out or returns non-2xx, Datamagnet retries up to 3 times with exponential backoff. Acknowledge immediately and process asynchronously to avoid timeouts:

Python (Flask)

from flask import request, jsonify
from threading import Thread

@app.route('/webhooks/signals', methods=['POST'])
def handle_signal():
    payload = request.json
    Thread(target=process_signal, args=(payload,)).start()
    return jsonify({"received": True}), 200

Getting Started

Concepts

Webhooks

Webhooks

Registering a webhook

Payload format by signal type

job_change · new_post

Engagement signals

Engagement signal payload fields

Top level

Per-lead fields

job_change · new_post payload fields

Verifying webhook signatures

Responding to webhooks

​Webhooks

​Registering a webhook

​Payload format by signal type

​job_change · new_post

​Engagement signals

​Engagement signal payload fields

​Top level

​Per-lead fields

​job_change · new_post payload fields

​Verifying webhook signatures

​Responding to webhooks

Webhooks

Registering a webhook

Payload format by signal type

job_change · new_post

Engagement signals

Engagement signal payload fields

Top level

Per-lead fields

job_change · new_post payload fields

Verifying webhook signatures

Responding to webhooks