# Employee Webhooks

Employee Webhooks send alerts when changes occur in key employee profile data fields. Subscribe and automatically receive updates reflecting the latest changes in employee records that matter to you.

Find endpoints and subscription examples in the corresponding topics:

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Base Employee webhooks</td><td><a href="../../employee-api/base-employee-api/endpoints/webhook-subscriptions">webhook-subscriptions</a></td></tr><tr><td>Clean Employee webhooks</td><td><a href="../../employee-api/clean-employee-api/endpoints/webhook-subscriptions">webhook-subscriptions</a></td></tr><tr><td>Multi-source Employee webhooks</td><td><a href="../../employee-api/multi-source-employee-api/webhook-subscriptions">webhook-subscriptions</a></td></tr></tbody></table>

## Subscription frequency

Delivery frequency is determined by the specific API data source you are utilizing. Corresponding cadence:

| API source                | Update frequency |
| ------------------------- | ---------------- |
| Base Employee API         | Daily            |
| Clean Employee API        | Weekly           |
| Multi-Source Employee API | Weekly           |

{% hint style="info" %}
**Multi-source, Clean, or Base?**

* **Multi-source datasets** contain cleaned and enriched data combining information from multiple sources.
* **Clean datasets** are derived from our Base data and cleaned to ensure the best quality.
* **Base datasets** freshly scraped and structured/updated for easier use.
  {% endhint %}

## Functionality

1. Choose the employees you want to track (using an IDs list, search filter query, or Elasticsearch DSL filter query).
2. Provide a callback URL to receive notifications.
3. Receive notifications at your URL and retrieve the data using the corresponding APIs collection or Bulk Collect endpoints.

### Subscribe by field

By default, Employee Webhooks trigger on **any** change to a tracked profile. The **subscribe by field** feature lets you narrow your subscription to only receive notifications when specific fields are updated.

You still define your tracked population using IDs, Search filters, or Elasticsearch DSL queries. The `tracked_fields` parameter acts as an additional filter on top of that population, specifying which fields to watch.

{% hint style="info" %}

#### **Example**

You are tracking 500 employees by IDs but only care about `skills` changes. By adding `"tracked_fields": ["skills"]` to your subscription request, you will only receive webhooks when the `skills` field is updated – all other field changes are ignored.
{% endhint %}

### Webhook triggers

The following employee profile fields are tracked for changes. When any of these fields are updated, a webhook notification is sent.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Base Employee webhook triggers</td><td><a href="../../../employee-api/base-employee-api/endpoints/webhook-subscriptions#webhook-triggers">#webhook-triggers</a></td></tr><tr><td>Clean Employee webhook triggers</td><td><a href="../../../employee-api/clean-employee-api/endpoints/webhook-subscriptions#webhook-triggers">#webhook-triggers</a></td></tr><tr><td>Multi-source Employee webhook triggers</td><td><a href="../../../employee-api/multi-source-employee-api/webhook-subscriptions#webhook-triggers">#webhook-triggers</a></td></tr></tbody></table>

## Webhook payload

Each webhook notification includes the following fields:

* `member_id` – The ID of the employee profile that was updated.
* `status` – The type of change detected (see status values below).
* `changed_fields` – An array listing the specific fields that were modified on the profile.

{% code title="Example payload" %}

```json
[
  {
    "member_id": 123,
    "status": "started_matching_query",
    "changed_fields": null
  },
  {
    "member_id": 124,
    "status": "stopped_matching_query",
    "changed_fields": null
  },
  {
    "member_id": 125,
    "status": "changed",
    "changed_fields": ["skills", "headline", "certifications"]
  }
]
```

{% endcode %}

The `changed_fields` array tells you exactly which parts of the profile were modified. You can use this to decide whether to retrieve the full updated profile or skip the notification based on your use case.

## Status values

| Status                   | Description                                                                                                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `started_matching_query` | Profiles that previously did not match your filters have been updated to meet your criteria. *Example:* a job title was updated to `Project Manager`.                                                               |
| `stopped_matching_query` | Profiles that once matched your filters have been updated and no longer match. *Example:* a job title changed from `Project Manager` to `Scrum Master`.                                                             |
| `changed`                | One or more tracked fields on the profile were updated. The `changed_fields` array in the payload shows which specific fields were modified. To retrieve the new values, use the Collect or Bulk Collect endpoints. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coresignal.com/api-introduction/webhooks/employee-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.