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.

See all event types

Webhook Security

To verify that webhooks are coming from SemantikMatch, you should validate the signature included in the x-semantikmatch-signature header.

The signature is a SHA-256 HMAC hash of the raw request body, using your webhook secret as the key. Compare this hash with the signature in the header to ensure the request is authentic.

You can find your webhook secret in your SemantikMatch dashboard under Settings » Webhooks.

Complete Server Examples

This section provides complete examples of setting up a server to handle webhooks from SemantikMatch.

Webhook Integration

Set up a webhook endpoint to receive evaluation results from SemantikMatch when a candidate's evaluation is complete.

from flask import Flask, request, jsonify
import hmac
import hashlib
import json

app = Flask(__name__)

# Your webhook secret from SemantikMatch
WEBHOOK_SECRET = "your_secret_key"

def verify_signature(payload_str, signature):
    """Verify the webhook signature."""
    computed_signature = hmac.new(
        WEBHOOK_SECRET.encode('utf-8'),
        payload_str.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(computed_signature, signature)

@app.route('/webhook/score', methods=['POST'])
def receive_score():
    # Get the signature from headers
    signature = request.headers.get('x-semantikmatch-signature')
    
    # Get the raw payload
    payload = request.get_data()
    payload_str = payload.decode('utf-8')
    
    # Verify signature if provided
    if signature and not verify_signature(payload_str, signature):
        return jsonify({"error": "Invalid signature"}), 403
    
    # Parse the payload
    data = request.json
    
    # Extract key information
    application_id = data.get('applicationId')
    total_score = data.get('totalScore')
    first_name = data.get('firstName')
    last_name = data.get('lastName')
    email = data.get('email')
    
    # Get client data that was included during submission
    client_data_str = data.get('client_data', '{}')
    client_data = json.loads(client_data_str) if isinstance(client_data_str, str) else client_data_str
    
    # Get candidate ID from client data
    candidate_id = client_data.get('candidate_id')
    
    # Process the score - update your CRM, database, etc.
    if candidate_id:
        # Update candidate status in your system
        update_candidate_in_crm(candidate_id, total_score, data)
    
    return jsonify({"status": "success"})

def update_candidate_in_crm(candidate_id, score, evaluation_data):
    """
    Update candidate information in your CRM.
    Implement according to your CRM's API.
    """
    # Example placeholder - implement according to your CRM
    print(f"Updating candidate {candidate_id} with score {score}")
    
    # Extract detailed criteria results
    criteria_results = []
    for criterion in evaluation_data.get('criteria', []):
        criteria_results.append({
            'name': criterion.get('custom_name', 'Unknown'),
            'score': criterion.get('score'),
            'payload': criterion.get('payload')
        })
    
    # Your CRM update logic here
    # Example: your_crm_api.update_candidate(candidate_id, score, criteria_results)

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Webhook Payload Example

{
  "applicationId": "13b6f1ad-2223-49ec-b916f2df1c09",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "totalScore": 85.5,
  "criteria": [
    {
      "id": "criteria_id",
      "score": 100,
      "score_justification": "Justification text",
      "confidence": 0.95,
      "confidence_justification": "Confidence justification",
      "payload": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  ],
  "client_data": "{\"candidate_id\":\"CRM-12345\",\"source\":\"internal_system\"}"
}

This webhook handler will:

Verify the webhook signature for security
Parse the payload data
Extract key information about the candidate and scores
Process the results and update your systems

Event Types

SemantikMatch can notify your application about various events through webhooks. Here are the main event types you can listen for:

Application Events

Name
application.created
Description
Triggered when a new application is created.
Name
application.updated
Description
Triggered when an application is updated.
Name
application.completed
Description
Triggered when a candidate completes an application.

Evaluation Events

Name
evaluation.started
Description
Triggered when the evaluation process begins.
Name
evaluation.progressed
Description
Triggered when the evaluation reaches a new stage.
Name
evaluation.completed
Description
Triggered when the evaluation is fully completed.
Name
evaluation.failed
Description
Triggered when there's an error during evaluation.

Scoring Events

Name
scoring.updated
Description
Triggered when a candidate's score is updated.
Name
scoring.finalized
Description
Triggered when the final score is calculated.

Best Practices

When implementing webhooks, consider the following best practices:

Always verify signatures - This ensures webhooks are actually from SemantikMatch.
Implement idempotency - Process each webhook exactly once, even if you receive duplicate requests.
Respond quickly - Your endpoint should acknowledge receipt promptly, even if processing takes longer.
Handle retries - SemantikMatch will retry failed webhook deliveries, so design your system to handle retries gracefully.
Log webhook data - Keep a record of received webhooks for debugging and auditing.
Use a queue - For time-consuming processing, acknowledge the webhook immediately and process it asynchronously.
Monitor webhook health - Set up monitoring to detect when webhooks aren't being received as expected.