Skype Interviews API offers a wide range of capabilities from creating interviews, scheduling interviews, retrieving feedback to position and tenant management.
Today, we are happy to announce “webhooks” capability for Skype Interviews. We reworked our authentication model to be more robust and secure to enable this awesome feature.
What is a webhook?
Webhooks allow you to subscribe to event changes of Interviews and allows your app to immediately react to changes to the interview.
Let’s assume your app needs to send out an automatic report of a candidate to your company’s lead engineering manager. The report should contain all the code that the candidate has written, as well as notes and feedback from the interviewer about the candidate.
With webhooks set up, we will notify you that the interview has reached the “InterviewCompleted” stage and then your app can use our “interview data retrieval API” to extract the candidate’s code and the notes from the interviewer.
How do I setup webhooks?
If you just want a NodeJS sample, you can check out our project on Glitch that you can remix. Just follow the instructions in the Readme file to see how it works.
If you don’t prefer NodeJS or want a more theoretical explanation, please read on!
There are 2 things you need to do.
First, create your HTTPS POST endpoint and enter it into the “Webhook URL” field in the developer settings. The link must be HTTPS and has to respond within 30 seconds.
- Verify the signature itself:
- Take the header and payload of the token
- Sign it again and verify that the newly created token is the same as the received one
var received_token = REQUEST.headers['Authorization'].replace("Bearer ", "") var splits = received_token.split('.') var signature = HMACSHA256( splits + "." + splits, API_SECRET) var new_token = splits + "." + splits + "." signature assert(received_token == new_token);
- Verify that the token is issued from your company
- The “iss” (Issuer) property of the payload needs to be equal to your company’s API Key
var payload = Base64decode(splits) asssert( API_KEY == payload.iss)
- Verify that the token didn’t expire
- The “iat” (Issued At) property of the payload is in the past
- The “exp” (Expiration Time) property of the payload is in the future
var payload = Base64decode(splits) assert( date.now() > payload.iat) assert( date.now() < payload.exp)
- Verify that event payload (the HTTPS request’s body) is not manipulated
- The “sub” (Subject) property of the payload is equal to the SHA256 hash of the request body
var payload = Base64decode(splits) assert( sha256(REQUEST.body) == payload.sub)
When will a webhook event get fired?
Right now, we’ll send you an event every time the interview stage changes. You can find all the events listed here:
|InterviewCreated||When a recruiter creates a new interview.|
|InterviewCanceled||When the recruiter cancels the interview.|
|InterviewArchived||When the recruiter archives the interview.|
|SchedulingTime||When either the candidate or interviewer is asked to propose or select a time slot. You can identify the role and action through the metadata variable.|
|SchedulingFailed||When an error occurs during the interview scheduling process.|
|SchedulingCompleted||When the interview has been scheduled and a time has been set.|
|InterviewStarted||When the interview has started and at least two participants joined the call.|
|InterviewFailed||When an error occured during the interview.|
|InterviewCompleted||When the a participant has clicked on the “End interview” button after InterviewStarted fired.|
|FeedbackCollecting||When the interview has ended and is awaiting the interviewer to submit feedback.|
|FeedbackFailed||When an error occured while submitting the feedback.|
|FeedbackCompleted||When the interviewer submitted feedback.|