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

Every delivery is one JSON object with a top-level event field:

Signal types	`event` values
`job_change`, `new_post`, `person_activity`	`"baseline"` when profiles start being tracked, then the signal type (`"job_change"`, `"new_post"`, `"person_activity"`) when something changes
Engagement signals	The signal type, such as `"keyword_engagement"`

job_change · new_post · person_activity

The first run for each profile records a baseline and sends a baseline event listing the profiles now tracked. After that, each run that finds changes sends one delivery with every change in changes. job_id and job_name are the signal’s signal_id and name, so you can tell apart several signals of one type. A profile tracked by two signals appears in a delivery from each.

baseline

{
  "event": "baseline",
  "user_email": "user@example.com",
  "job_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
  "job_name": "Champions",
  "signal_type": "job_change",
  "profiles": [
    { "profile_url": "https://www.linkedin.com/in/satyanadella", "profile_name": "Satya Nadella" }
  ]
}

job_change

{
  "event": "job_change",
  "user_email": "user@example.com",
  "job_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
  "job_name": "Champions",
  "signal_type": "job_change",
  "changes": [
    {
      "event_id": "0c6f2e1a-8d4b-4f3a-9c7e-5b1a2d3e4f60",
      "profile_url": "https://www.linkedin.com/in/janedoe",
      "profile_name": "Jane Doe",
      "signal_type": "job_change",
      "change_summary": "Jane Doe started a new role as VP Sales at Acme Corp.",
      "confidence": 0.95,
      "detected_at": "2026-09-23T11:23:10.412345+00:00",
      "change_data": {
        "change_detected": true,
        "confidence": 0.95,
        "summary": "Jane Doe started a new role as VP Sales at Acme Corp.",
        "change_type": "new_job"
      }
    }
  ]
}

new_post

{
  "event": "new_post",
  "user_email": "user@example.com",
  "job_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "job_name": "New Post Monitor",
  "signal_type": "new_post",
  "changes": [
    {
      "event_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "profile_url": "https://www.linkedin.com/in/reidhoffman",
      "profile_name": "Reid Hoffman",
      "signal_type": "new_post",
      "change_summary": "Posted 2 new updates about AI agents and startup hiring.",
      "confidence": 0.95,
      "detected_at": "2026-09-23T11:23:10.412345+00:00",
      "change_data": {
        "change_detected": true,
        "confidence": 0.95,
        "summary": "Posted 2 new updates about AI agents and startup hiring.",
        "new_post_count": 2,
        "new_posts_link": [
          "https://www.linkedin.com/posts/reidhoffman_ai-agents-activity-7506405584091541505-fa6g",
          "https://www.linkedin.com/posts/reidhoffman_hiring-activity-7506398765432101234-bc34"
        ],
        "topics": ["AI agents", "startup hiring"]
      }
    }
  ]
}

For person_activity, changes holds one entry per reaction, comment, or reply. See the Person Activity guide for its payload.

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

{
  "event": "keyword_engagement",
  "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

{
  "event": "company_engagement",
  "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

{
  "event": "industry_engagement",
  "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

{
  "event": "person_engagement",
  "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

Missed a delivery, or want the history? /signal/leads returns your stored leads with these same fields, on request.

Top level

string

Same as signal_type.

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 · person_activity payload fields

Top level

string

"baseline", or the signal type when there are changes.

string

The account email that owns the signal.

string

The signal’s signal_id.

string

The signal’s display name.

string

"job_change", "new_post", or "person_activity".

array

baseline events only. Each newly tracked profile: profile_url, profile_name.

array

Change events only. One entry per change, with the fields below.

Per-change fields

string

Unique ID of this change. Use it to de-duplicate on your side.

string

The tracked LinkedIn profile.

string

Full name of the tracked person.

string

"job_change" or "new_post"; for person_activity, "reaction", "comment", or "reply".

string

One or two sentences describing the change.

number | null

How sure the detection is, from 0.0 to 1.0. null for person_activity.

string

ISO 8601 time the change was detected.

object

Details of the change.

Show job_change

string

Same as change_summary.

number

Same as confidence.

string

"new_job", "promotion", or "same_company".

boolean

Always true.

Show new_post

string

Same as change_summary.

number

Same as confidence.

integer

How many new posts were found.

array

URLs of the new posts.

array

Main topics of the new posts.

boolean

Always true.

Show person_activity

See the Person Activity guide.

When the change could not be analysed in detail, change_data also has "_llm_fallback": true and a shorter, generic summary. The change itself is real.

Verifying webhook signatures

If you set a webhook_secret, every request includes an X-Datamagnet-Signature header: sha256= followed by the hex HMAC-SHA256 of the raw request body, signed with your secret. The same value is also sent as X-Signature-256.

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 = "sha256=" + 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 = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader || '')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

function verifySignature(string $secret, string $rawBody, string $signatureHeader): bool {
    $expected = 'sha256=' . 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 an error, Datamagnet retries the same payload:

Attempt	When (approximately)
1	Immediately
2	5 minutes later
3	30 minutes later
4	2 hours later
5	8 hours later
6	24 hours later
7	48 hours later

A 400, 401, 403, or 404 response means the endpoint is misconfigured, so it is retried once and then dropped. Use event_id (profile signals) to ignore a change you already processed. 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 · person_activity

Engagement signals

Engagement signal payload fields

Top level

Per-lead fields

job_change · new_post · person_activity payload fields

Top level

Per-change fields

Verifying webhook signatures

Responding to webhooks

​Webhooks

​Registering a webhook

​Payload format by signal type

​job_change · new_post · person_activity

​Engagement signals

​Engagement signal payload fields

​Top level

​Per-lead fields

​job_change · new_post · person_activity payload fields

​Top level

​Per-change fields

​Verifying webhook signatures

​Responding to webhooks

Webhooks

Registering a webhook

Payload format by signal type

job_change · new_post · person_activity

Engagement signals

Engagement signal payload fields

Top level

Per-lead fields

job_change · new_post · person_activity payload fields

Top level

Per-change fields

Verifying webhook signatures

Responding to webhooks