Announcing Webhooks for Skype Interviews

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.

Second, you need to verify our requests. With every request, we send an “Authorization” header that contains a JSON Web Token. There are already existing libraries that verify the token itself on JWT.IO,which is what we strongly recommend you to use. If you want to do it manually, it breaks down into 4 essential steps:
  1. 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[0] + "." + splits[1],   API_SECRET)
      var new_token = splits[0] + "." + splits[1] + "." signature
      assert(received_token ==  new_token);
  2. 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[1])
      asssert( API_KEY ==  payload.iss)
  3. 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[1])
      assert( > payload.iat)
      assert( < payload.exp)
  4. 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[1])
      assert( sha256(REQUEST.body) == payload.sub)
Once all these conditions are met, you can use the request’s body with the guarantee that Skype has issued the request and the content was not manipulated.

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:

Stage name Description
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.


Have some more questions? You can always check out our documentation or reach out to us via email!