TalentLyft API
HelpLoginRegisterGo to AppGo to TalentLyftRequest a Demo
  • 🎯Getting started
  • 🖥️Requests
  • 📨Responses
  • 🔐Authorization
  • ⚙️Customer API reference
    • Candidates
    • Departments
    • Employees
    • Events
    • Forms
    • Jobs
    • Members
    • Pipelines
    • Rejection reasons
    • Subscriptions
    • Articles
  • ⚙️Public API reference
    • Jobs
    • Departments
    • Locations
  • ⚙️Partner API reference
    • Assessments
    • HRIS & Onboarding
    • Background checks
    • Video Interviews
    • Job Boards
    • Sourcing & Employee referrals
Powered by GitBook
On this page
  1. Customer API reference

Subscriptions

A Webhook subscription lets you register a URL which will have notifications posted to it.

PreviousRejection reasonsNextArticles

Last updated 1 year ago

You can use webhooks to receive notifications. Webhooks are a powerful resource that you can use to automate your use cases and improve your productivity. .

Unlike the API resources, which represent static data that you can create, update and retrieve as needed, webhooks represent dynamic resources. You can configure them to automatically notify you when a candidate has taken a particular action, such as candidate move or hired.

The main concepts for webhooks are subscriptions, topics, and notifications.

Subscriptions

A Webhook subscription lets you register a URL which will have notifications posted to it.

{
    "Id": "0f706a09-fc01-4030-a07e-273bfde9bb47",
    "ServiceType": "Web",
    "Url": "string",
    "HubSecret": "d6376ec0-acfc-4820-8eb2-350454b66075",
    "Created": "2019-06-07T20:39:39.495Z",
    "Updated": "2019-06-07T20:39:39.495Z",
    "Topics": ["candidate.sourced", "candidate.applied", "candidate.hired"]
}

Topics

A subscription will contain one or more topics. List of available topics:

Topic Description

Topic label

Candidate sourced

candidate.sourced

Candidate applied

candidate.applied

Candidate hired

candidate.hired

The candidate moved to stage

candidate.moved

Candidate evaluated

candidate.evaluated

Candidate disqualified

candidate.disqualified

Candidate revert

candidate.revert

Candidate commented

candidate.note

Candidate external comment

candidate.externalnote

A candidate submitted assessment result

candidate.assessment

Candidate replied

candidate.inboundemail

Candidate merged

candidate.merged

Candidate task created

candidate.task

Candidate task completed

candidate.taskcompleted

The candidate is woken up

candidate.wokenup

Candidate form submitted

candidate.formsubmission

Job published

job.published

Job updated

job.updated

An event is created

event.created

An event's title, time, or location is updated

event.updated

An event is canceled or removed

event.deleted

An event attendee status is updated

event.attendeestatus

Blog post edited

post.updated

Blog post published

post.published

GDPR - candidate delete data

gdpr.delete

GDPR - candidate edit request

gdpr.editrequest

Job requisition status change

job.jobrequisitionstatuschange

Notifications

The object delivered to a webhook is a notification. Notifications have payloads, which contain the API's existing JSON objects, such as candidate or job.

{
  "Uid": "c78d0bee-f4b2-475d-8ca1-de78675888d3",
  "Topic": "candidate.hired",
  "Created": "2019-06-07T20:39:39.495Z",
  "FirstSentAt": "2019-06-07T20:39:39.495Z",
  "DeliveryAttempts": 1,
  "SubscriptionId": "5ec42730-9a19-4ccc-acb0-aefdd3426215",
  "Payload": [
    {
      "Type": "Candidate",
      "Data": {}
    }
  ]
}

Payload types

Payload types list

Type

Description

Candidate

Candidate

CandidateApplication

Application

CandidateEvent

Event

CandidateNote

Note

CandidateEvaluation

Evaluation

CandidateAssessment

Assessment

CandidateTask

Task

CandidateEmail

Email

ProfileMentioned

Profile

ProfileActionperformer

Profile

Signed Notifications

You can request notifications from TalentLyft are signed by adding a HubSecret field to the subscription. The value of the HubSecret is used as the key to create a hash signature of the JSON notification The digest is then sent using an X-TL-Signature header in the request and can be verified by the receiving webhook.

The X-TL-Signature header value starts with the string sha1= followed by the signature - for example, X-TL-Signature: sha1=21ff2e149e0fdcac6f947740f6177f6434bda921.

Retries

Webhook events are sent as json encoded POST request to URL you have specified in your development settings. For each sent webhook if response status code is equal or greater then 300 event will be sent again after 10 minutes. TalentLyft will try to resend each webhook 5 times in total.

If response code is >= 300 after all 5 attempts, this event will be discarded. If number of failed attempts reaches failure limit (50 failures), webhook will be suspended and no further deliveries will be made. Suspended webhooks can't be activated.

Network restrictions

If you are setting any network restrictions, please let us know so we can send you the list of Ip addresses that you need to allow traffic from for the integration to work.

Duplicated message

Because of possible network or other failures, there can be a duplicated messages that are sent to your webhook endpoint. To process this correctly on your side each event has Id property that will be same for each webhook retry. You can use this identificator to ignore already sent messages.

The signature is the hexadecimal (40-byte) representation of a SHA-1 signature computed using the HMAC algorithm as defined in .

⚙️
You can find more about them through this link if you're unfamiliar
RFC2104

View Subscriptions

get
Authorizations
Header parameters
X-TL-CompanyIdguidOptional

Company Id

X-TL-SubdomainguidOptional

Account subdomain

X-TL-UserIdguidOptional

Team member id

Responses
200
Success
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
500
Server Error
application/json
get
GET /v2/subscriptions HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
[
  {
    "Id": "123e4567-e89b-12d3-a456-426614174000",
    "ServiceType": "Web",
    "Url": "text",
    "HubSecret": "text",
    "Created": "2025-05-16T20:37:16.241Z",
    "Updated": "2025-05-16T20:37:16.241Z",
    "Topics": [
      "text"
    ],
    "AdditionalData": "text"
  }
]

View a Subscription

get
Authorizations
Path parameters
idstring · uuidRequired
Header parameters
X-TL-CompanyIdguidOptional

Company Id

X-TL-SubdomainguidOptional

Account subdomain

X-TL-UserIdguidOptional

Team member id

Responses
200
Success
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
application/json
500
Server Error
application/json
get
GET /v2/subscriptions/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
{
  "Id": "123e4567-e89b-12d3-a456-426614174000",
  "ServiceType": "Web",
  "Url": "text",
  "HubSecret": "text",
  "Created": "2025-05-16T20:37:16.241Z",
  "Updated": "2025-05-16T20:37:16.241Z",
  "Topics": [
    "text"
  ],
  "AdditionalData": "text"
}

Delete a Subscription

delete
Authorizations
Path parameters
idstring · uuidRequired
Header parameters
X-TL-CompanyIdguidOptional

Company Id

X-TL-SubdomainguidOptional

Account subdomain

X-TL-UserIdguidOptional

Team member id

Responses
204
No Content
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
application/json
500
Server Error
application/json
delete
DELETE /v2/subscriptions/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

  • Subscriptions
  • Topics
  • Notifications
  • Payload types
  • Signed Notifications
  • Retries
  • Network restrictions
  • Duplicated message
  • GETView Subscriptions
  • POSTCreate a Subscriptions
  • GETView a Subscription
  • PUTUpdate a Subscription
  • DELETEDelete a Subscription

Create a Subscriptions

post
Authorizations
Header parameters
X-TL-CompanyIdguidOptional

Company Id

X-TL-SubdomainguidOptional

Account subdomain

X-TL-UserIdguidOptional

Team member id

Body
Idstring · uuidOptional
ServiceTypestring · enumOptionalPossible values:
Urlstring | nullableOptional
HubSecretstring | nullableOptional
Createdstring · date-timeOptional
Updatedstring · date-timeOptional
Topicsstring[] | nullableOptional
AdditionalDatastring | nullableOptional
Responses
201
Created
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
409
Conflict
application/json
500
Server Error
application/json
post
POST /v2/subscriptions HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 213

{
  "Id": "123e4567-e89b-12d3-a456-426614174000",
  "ServiceType": "Web",
  "Url": "text",
  "HubSecret": "text",
  "Created": "2025-05-16T20:37:16.241Z",
  "Updated": "2025-05-16T20:37:16.241Z",
  "Topics": [
    "text"
  ],
  "AdditionalData": "text"
}
{
  "Id": "123e4567-e89b-12d3-a456-426614174000",
  "ServiceType": "Web",
  "Url": "text",
  "HubSecret": "text",
  "Created": "2025-05-16T20:37:16.241Z",
  "Updated": "2025-05-16T20:37:16.241Z",
  "Topics": [
    "text"
  ],
  "AdditionalData": "text"
}

Update a Subscription

put
Authorizations
Path parameters
idstring · uuidRequired
Header parameters
X-TL-CompanyIdguidOptional

Company Id

X-TL-SubdomainguidOptional

Account subdomain

X-TL-UserIdguidOptional

Team member id

Body
Idstring · uuidOptional
ServiceTypestring · enumOptionalPossible values:
Urlstring | nullableOptional
HubSecretstring | nullableOptional
Createdstring · date-timeOptional
Updatedstring · date-timeOptional
Topicsstring[] | nullableOptional
AdditionalDatastring | nullableOptional
Responses
204
No Content
401
Unauthorized
application/json
403
Forbidden
application/json
404
Not Found
application/json
409
Conflict
application/json
422
Client Error
application/json
500
Server Error
application/json
put
PUT /v2/subscriptions/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 213

{
  "Id": "123e4567-e89b-12d3-a456-426614174000",
  "ServiceType": "Web",
  "Url": "text",
  "HubSecret": "text",
  "Created": "2025-05-16T20:37:16.241Z",
  "Updated": "2025-05-16T20:37:16.241Z",
  "Topics": [
    "text"
  ],
  "AdditionalData": "text"
}

No content