Webhooks & Notifications
A Webhook subscription lets you register a URL which will have notifications posted to it.
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. You can find more about them through this link if you're unfamiliar.
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

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 signature is the hexadecimal (40-byte) representation of a SHA-1 signature computed using the HMAC algorithm as defined in RFC2104.
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.

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.
get
https://api.talentlyft.com
/v2/subscriptions
Get subscriptions
get
https://api.talentlyft.com
/v2/subscriptions/:id
Get subscription
post
https://api.talentlyft.com
/v2/subscriptions
Create subscription
put
https://api.talentlyft.com
/v2/subscriptions/:id
Update subscription
post
https://api.talentlyft.com
/v2/subscriptions
delete
https://api.talentlyft.com
/v2/subscriptions/:id
Delete subscription
Copy link
On this page
Subscriptions
Topics
Notifications
Payload types
Signed Notifications
Retries
Duplicated message
get
Get subscriptions
get
Get subscription
post
Create subscription
put
Update subscription
post
delete
Delete subscription