Webhooks
In this guide, we will look at how to register and consume webhooks to integrate your app with Semantikmatch. With webhooks, your app can know when something happens in Semantikmatch, such as the completion of an evaluation or submission of an application.
Registering webhooks
To register a new webhook, you need to have a URL in your app that Semantikmatch can call. You can configure a new webhook from the Semantikmatch dashboard under API settings. Give your webhook a name, pick the events you want to listen for, and add your URL.
Now, whenever something of interest happens in Semantikmatch, a webhook is fired off by Semantikmatch. In the next section, we'll look at how to consume webhooks.
Consuming webhooks
When your app receives a webhook request from Semantikmatch, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., an evaluation, application, etc.
Example webhook payload
{
"id": "a056V7R7NmNRjl70",
"type": "evaluation.completed",
"payload": {
"application_id": "WAz8eIbvDR60rouK",
"global_score": 100,
"candidate": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@semantikmatch.com"
},
"criteria": [
{
"criteriaId": "1",
"criteria_type": "experience",
"score": 100,
"details": "The candidate has a total of 56 months of experience that satisfy the managerial requirement: 24 months as Directeur Data & Intelligence Artificielle at ESSEC Business School and 12 months at both INSERM and ARS managing data teams.",
"citations": [
"ESSEC Business Schoolmai 2022 - avril 2024 Directeur Data & Intelligence Artificielle... Management de la gouvernance... Management de la direction et de l’équipe...",
"INSERMseptembre 2021 - mai 2022 Responsable du domaine data management... Management d'une équipe de 4 collaborateurs...",
"Agence Régionale de Santé - Ile de Franceseptembre 2020 - août 2021 Responsable du département Data... Management d'une équipe de 4 personnes..."
],
"confidence": "The agent correctly calculated the candidate's experience in managerial positions. The roles of Directeur Data & Intelligence Artificielle at ESSEC Business School (24 months), Responsable du domaine data management at INSERM (9 months, September 2021 - May 2022), and Responsable du département Data at the Agence Régionale de Santé - Ile de France (12 months) do indeed sum to 45 months of relevant managerial experience, satisfying the criterion with substantial evidence provided from each role.",
"attachment_url": "https://example.com/attachment/experience"
},
{
"criteriaId": "2",
"criteria_type": "academic",
"score": 100,
"details": "The document explicitly states that the diploma confers the grade of Master, which meets the criterion of being equal to or higher than a Master's degree.",
"citations": [
"Conférant le grade de Master",
"L’attribution du diplôme de l’Institut d’Etudes Politiques de Paris confère le grade universitaire de Master"
],
"confidence": "The agent correctly identified that the academic level conferred by the diploma is a Master's degree, as explicitly stated in the content. This meets the criterion of being equal to or higher than a Master's degree.",
"attachment_url": "https://example.com/attachment/academic"
},
{
"criteriaId": "3",
"criteria_type": "language",
"score": 100,
"details": "The extracted TOEIC total score is 930, which is higher than the criterion of 900.",
"citations": [
"Total Score: 930"
],
"confidence": "The agent correctly extracted and evaluated the TOEIC total score of 930 from the content, which is indeed higher than the criterion of 900. The extracted value directly matches the 'Total Score' mentioned in the content, confirming the accuracy of the agent's result.",
"attachment_url": "https://example.com/attachment/language"
}
]
}
}
In the example above, an evaluation was completed, and the payload type is an evaluation.
Security
To know for sure that a webhook was, in fact, sent by Semantikmatch instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-semantikmatch-signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:
Verifying a request
const signature = req.headers['x-semantikmatch-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')
if (hash === signature) {
// Request is verified
} else {
// Request could not be verified
}
If your generated signature matches the x-semantikmatch-signature header, you can be sure that the request was truly coming from Semantikmatch. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Semantikmatch. Don't commit your secret webhook key to GitHub!
Complete Server Examples
This section provides a unified example of setting up a server to handle webhooks using cURL, Python (Flask), and JavaScript (Node.js with Express). The server verifies the request signature to ensure the webhook is from a trusted source.
Unified Server Module
# Python (Flask)
from flask import Flask, request, jsonify
import hashlib
import hmac
app = Flask(__name__)
# Replace 'your_secret_key' with your actual secret key
SECRET_KEY = 'your_secret_key'
def verify_signature(payload, signature):
hash = hmac.new(bytes(SECRET_KEY, 'ascii'), bytes(payload, 'ascii'), hashlib.sha256)
return hmac.compare_digest(hash.hexdigest(), signature)
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get("x-semantikmatch-signature")
payload = request.get_data(as_text=True)
if not verify_signature(payload, signature):
return jsonify({"status": "error", "message": "Invalid signature"}), 403
data = request.get_json()
return jsonify({"status": "success", "message": "Data received"}), 200
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5003)
This unified module provides a comprehensive example of how to set up a webhook server in both Python and JavaScript, ensuring secure verification of incoming requests.