> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datamagnet.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time Datamagnet signal notifications via HTTP POST to your server, including payload format, retry behavior, and signature verification.

# 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](https://docs.datamagnet.co/api-reference/endpoints/signal-create.md) or update it later via [/signal/update](https://docs.datamagnet.co/api-reference/endpoints/signal-update.md).

```json Example theme={null}
{
  "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.

```json baseline theme={null}
{
  "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" }
  ]
}
```

```json job_change theme={null}
{
  "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"
      }
    }
  ]
}
```

```json new_post theme={null}
{
  "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](https://docs.datamagnet.co/api-reference/endpoints/signal-person-activity.md#webhook-payload) 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`.

```json keyword_engagement example theme={null}
{
  "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"
    }
  ]
}
```

```json company_engagement example theme={null}
{
  "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"
    }
  ]
}
```

```json industry_engagement example theme={null}
{
  "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"
    }
  ]
}
```

```json person_engagement example theme={null}
{
  "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](https://docs.datamagnet.co/api-reference/endpoints/signal-leads.md) returns your stored leads with these same fields, on request.

### Top level

**event** `string`

Same as `signal_type`.

**user\_email** `string`

The account email that owns the signal.

**signal\_type** `string`

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

**run\_stats** `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`.

**leads** `array`

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

### Per-lead fields

**linkedin\_url** `string`

The LinkedIn profile URL of the person who engaged.

**profile\_name** `string`

Full name of the engager.

**headline** `string`

Current LinkedIn headline of the engager.

**signal\_keyword** `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"`)

**engagement\_type** `string`

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

**engagement\_post\_url** `string`

URL of the LinkedIn post the person engaged with.

**engagement\_link** `string`

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

**comment\_text** `string | null`

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

**post\_excerpt** `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.

**post\_author** `string | null`

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

**lead\_score** `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`

**icp\_score** `number`

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

**signal\_score** `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.

**detected\_at** `string`

ISO 8601 timestamp of when the lead was scored.

***

## job\_change · new\_post · person\_activity payload fields

### Top level

**event** `string`

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

**user\_email** `string`

The account email that owns the signal.

**job\_id** `string`

The signal's `signal_id`.

**job\_name** `string`

The signal's display name.

**signal\_type** `string`

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

**profiles** `array`

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

**changes** `array`

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

### Per-change fields

**event\_id** `string`

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

**profile\_url** `string`

The tracked LinkedIn profile.

**profile\_name** `string`

Full name of the tracked person.

**signal\_type** `string`

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

**change\_summary** `string`

One or two sentences describing the change.

**confidence** `number | null`

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

**detected\_at** `string`

ISO 8601 time the change was detected.

**change\_data** `object`

Details of the change.

**job\_change**

**summary** `string`

Same as `change_summary`.

**confidence** `number`

Same as `confidence`.

**change\_type** `string`

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

**change\_detected** `boolean`

Always `true`.

**new\_post**

**summary** `string`

Same as `change_summary`.

**confidence** `number`

Same as `confidence`.

**new\_post\_count** `integer`

How many new posts were found.

**new\_posts\_link** `array`

URLs of the new posts.

**topics** `array`

Main topics of the new posts.

**change\_detected** `boolean`

Always `true`.

**person\_activity**

See the [Person Activity guide](https://docs.datamagnet.co/api-reference/endpoints/signal-person-activity.md#fields).

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`.

```python Python theme={null}
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)
```

```javascript Node.js theme={null}
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)
}
```

```php PHP theme={null}
function verifySignature(string $secret, string $rawBody, string $signatureHeader): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}
```

> [!WARNING]
>
> 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 Python (Flask) theme={null}
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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.