Webhook Subscriptions
The subscription is valid for 91 days. During this period, you'll receive notifications about all changes in the selected employee profiles or specific data points determined by the filters used.
Employee API subscription feature (or webhooks) enables you to track updates in selected profiles by setting up a callback URL to receive change notifications:
- Choose the profiles you want to track (using an ID list, search filter query, or ES DSL filter query).
- Provide a callback URL to receive notifications.
- Receive notifications to your URL and retrieve the data using the Employee API collection endpoint or Bulk Collect.
Use the following endpoints to subscribe to employee profile changes:
Function | Endpoint |
|---|---|
POST | /v1/subscriptions/professional_network/member/id_file |
POST | /v1/subscriptions/professional_network/member/filter |
POST | /v1/subscriptions/professional_network/member/es_dsl |
After creating a webhook subscription, you will begin receiving updates via webhooks next Monday. Updates will be sent once a week.
You will receive status updates indicating various types of changes in profiles matched by filters or IDs.
Different endpoints have different statuses listed below:
Status | Description |
|---|---|
Added | Profiles that previously did not match your filters have been updated to meet your criteria (e.g., the job title was updated to Project Manager). |
Removed | Profiles that once matched your filters but have since updated to no longer match (e.g., job title changed from Project Manager to Scrum Master). |
Changed | Profiles that have undergone non-specified changes. To see the exact changes, you will need to query them using Bulk Collect GET or Employee API collection endpoints. |
Status | Description |
|---|---|
Changed | Profiles that have undergone non-specified changes. To see the exact changes, you will need to query them using Bulk Collect GET or Employee API collection endpoints. |
Since we send information via webhooks once a week, you won't be able to see how the feature works right away after ordering a subscription.
Use the simulate endpoint to simulate an active webhook subscription.
Simulate endpoint URL: https://api.coresignal.com/cdapi/v1/subscriptions/simulate
Subscription simulation instructions.
We additionally offer endpoints for subscription management. Use them to list your active subscriptions, see the details, and delete irrelevant ones.
Endpoint | Function |
|---|---|
/v1/subscriptions | See all your subscriptions, their status, creation, and expiration dates. |
/v1/subscriptions/{subsription_id} | See all your subscriptions, their status, used filters or ES DSL schema, creation, expiration dates, and last webhook date. |
DELETE /v1/subscriptions/{subscription_id} | Delete your subscriptions. |
Subscription management details.
Use the same token you received for Employee API usage. Subscription requests do not consume credits like regular Employee API endpoints. The subscription feature is only accessible to the users of higher-tier API plans. To learn more about accessing this feature, contact your account manager.
To start using our API, you need a (JWT) token. Your account manager or sales will generate the token for you upon your request for the API plan.
All requests to the Webhook endpoints must contain an Authorization header consisting of a Bearer authentication string and the JSON Web Token (JWT).
All Employee API requests must be made over HTTPS. Requests made over HTTP will fail.
Use any API-compatible tool to authorize and start querying in the API. If you're unsure where to begin, check out the authorization tutorials:
The number of requests allowed from one client's API token per second is limited.
Function | Endpoint | Rate limits |
|---|---|---|
POST | /v1/subscriptions/professional_network/member/id_file | 9 requests per minute |
POST | /v1/subscriptions/professional_network/member/filter | 9 requests per minute |
POST | /v1/subscriptions/professional_network/member/es_dsl | 9 requests per minute |
Check the endpoint usage tutorials in the following articles: