Subscriptions

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

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.

View Subscriptions

GET/v2/subscriptions

Header parameters

Response

200401403500

Success

Body

application/json

Idstring (uuid)

ServiceTypeTalentLyft.Data.Enumerators.ServiceTypes (enum)

WebEmailInboxSlackTeams

Urlnullable string

HubSecretnullable string

Createdstring (date-time)

Updatedstring (date-time)

Topicsnullable array of string

AdditionalDatanullable string

Request

JavaScriptCurlPython

const response = await fetch('/v2/subscriptions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401403500

[
  {
    "Id": "123e4567-e89b-12d3-a456-426614174000",
    "ServiceType": "Web",
    "Url": "text",
    "HubSecret": "text",
    "Created": "2024-11-21T06:47:15.089Z",
    "Updated": "2024-11-21T06:47:15.089Z",
    "Topics": [
      "text"
    ],
    "AdditionalData": "text"
  }
]

Create a Subscriptions

POST/v2/subscriptions

Header parameters

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

Idstring (uuid)

ServiceTypeTalentLyft.Data.Enumerators.ServiceTypes (enum)

WebEmailInboxSlackTeams

Urlnullable string

HubSecretnullable string

Createdstring (date-time)

Updatedstring (date-time)

Topicsnullable array of string

AdditionalDatanullable string

Response

201401403409500

Created

Body

application/json

Idstring (uuid)

ServiceTypeTalentLyft.Data.Enumerators.ServiceTypes (enum)

WebEmailInboxSlackTeams

Urlnullable string

HubSecretnullable string

Createdstring (date-time)

Updatedstring (date-time)

Topicsnullable array of string

AdditionalDatanullable string

Request

JavaScriptCurlPython

const response = await fetch('/v2/subscriptions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

201401403409500

{
  "Id": "123e4567-e89b-12d3-a456-426614174000",
  "ServiceType": "Web",
  "Url": "text",
  "HubSecret": "text",
  "Created": "2024-11-21T06:47:15.089Z",
  "Updated": "2024-11-21T06:47:15.089Z",
  "Topics": [
    "text"
  ],
  "AdditionalData": "text"
}

View a Subscription

GET/v2/subscriptions/{id}

Path parameters

id*string (uuid)

Header parameters

Response

200401403404500

Success

Body

application/json

Idstring (uuid)

ServiceTypeTalentLyft.Data.Enumerators.ServiceTypes (enum)

WebEmailInboxSlackTeams

Urlnullable string

HubSecretnullable string

Createdstring (date-time)

Updatedstring (date-time)

Topicsnullable array of string

AdditionalDatanullable string

Request

JavaScriptCurlPython

const response = await fetch('/v2/subscriptions/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401403404500

{
  "Id": "123e4567-e89b-12d3-a456-426614174000",
  "ServiceType": "Web",
  "Url": "text",
  "HubSecret": "text",
  "Created": "2024-11-21T06:47:15.089Z",
  "Updated": "2024-11-21T06:47:15.089Z",
  "Topics": [
    "text"
  ],
  "AdditionalData": "text"
}

Update a Subscription

PUT/v2/subscriptions/{id}

Path parameters

id*string (uuid)

Header parameters

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

Idstring (uuid)

ServiceTypeTalentLyft.Data.Enumerators.ServiceTypes (enum)

WebEmailInboxSlackTeams

Urlnullable string

HubSecretnullable string

Createdstring (date-time)

Updatedstring (date-time)

Topicsnullable array of string

AdditionalDatanullable string

Response

204401403404409422500

No Content

Request

JavaScriptCurlPython

const response = await fetch('/v2/subscriptions/{id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

401403404409422500

{
  "Message": "text",
  "Errors": [
    {
      "Field": "text",
      "Message": "text"
    }
  ]
}

Delete a Subscription

DELETE/v2/subscriptions/{id}

Path parameters

id*string (uuid)

Header parameters

Response

204401403404500

No Content

Request

JavaScriptCurlPython

const response = await fetch('/v2/subscriptions/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

401403404500

{
  "Message": "text",
  "Errors": [
    {
      "Field": "text",
      "Message": "text"
    }
  ]
}