Webhooks

Introduction aux Webhooks

Les webhooks permettent à JobAffinity de notifier votre système lorsqu’une candidature change d’étape. Les notifications sont envoyées par lots, dans les minutes qui suivent le changement.

Événements disponibles

L’événement ProcessStepChange est émis à chaque changement d’étape d’une candidature. Si vous avez besoin d’autres événements, indiquez-le au support.

Configuration

Pour activer les webhooks, contactez le support d’Intuition-Software : support@intuition-software.fr, en indiquant l’URL HTTPS de votre endpoint. Une seule URL est configurée par organisation. Le corps de la notification ne contient aucune donnée personnelle : seulement des identifiants et des liens vers l’API REST. Nous recommandons d’inclure un jeton secret non devinable dans l’URL (par exemple https://exemple.fr/webhook/jobaffinity/7f3a9c2e...) et de rejeter tout appel qui ne le porte pas. Si vous avez d’autres besoins (authentification de l’appel, signature, événements supplémentaires), indiquez-le au support.

Format de la notification

JobAffinity envoie une requête POST avec un corps JSON :

{
  "_self": "/restapi/v1/application/42",
  "id": 42,
  "candidate": {
    "_self": "/restapi/v1/candidate/1337",
    "id": 1337
  },
  "job": {
    "_self": "/restapi/v1/job/7",
    "id": 7
  },
  "step": {
    "name": "Entretien",
    "status": "CURRENT",
    "date": "2026-10-21 00:00:00"
  }
}

_self, candidate._self, job._self : chemins à préfixer par https://jobaffinity.fr pour obtenir le détail via l’API REST
id, candidate.id, job.id : identifiants de la candidature, du candidat et de l’offre
step.name : nom de l’étape courante
step.status : position de l’étape dans le processus : START (première étape), CURRENT (étape intermédiaire) ou END (étape finale)
step.date : date d’entrée dans l’étape, au format YYYY-MM-DD HH:MM:SS

La notification décrit l’état de la candidature au moment de l’envoi. Si une candidature change plusieurs fois d’étape avant l’envoi, une seule notification est émise, portant la dernière étape. Traitez chaque notification comme un signal « cette candidature a changé » et relisez son état via l’API, plutôt que comme un journal d’événements.

Historique des appels Webhook

Vous pouvez consulter l’historique des appels webhook effectués par JobAffinity.

Requête

GET /restapi/v1/webhook/task

Réponse

{
  "_status": "OK",
  "_schema": "/restapi/schemav1/webhooktasks",
  "_self": "/restapi/v1/webhook/task",
  "_next": "",
  "items": [
    {
      "id": 1234,
      "event": "ProcessStepChange",
      "datetime": "2021-04-01 12:13:14",
      "response_body": "Server Error",
      "response_status": 500,
      "application": {
        "_self": "/restapi/v1/application/42"
      }
    }
  ]
}

Champs de la réponse

id : identifiant de l’appel, utilisé pour la pagination
event : Type d’événement déclenché
datetime : Date et heure de l’appel webhook
response_status : Code de statut HTTP retourné par votre endpoint, ou 0 si l’endpoint n’a pas pu être joint (le message d’erreur est alors dans response_body)
response_body : Corps de la réponse de votre endpoint
application : Référence à la candidature concernée

Cette ressource est paginée. Utilisez le champ _next pour parcourir l’historique complet.

Implémentation d’un endpoint

Bonnes pratiques

Répondez rapidement : Acquittez la requête puis traitez-la de façon asynchrone
Retournez un code 2xx : Le code et les 1024 premiers caractères de votre réponse sont conservés dans l’historique
Vérifiez le jeton : Rejetez les appels qui ne portent pas votre jeton secret
Rendez le traitement idempotent : Relisez l’état courant de la candidature via l’API à chaque notification
Loggez les appels : Conservez une trace des webhooks reçus pour le débogage

Chaque notification est envoyée une seule fois. En cas d’échec (erreur réseau, réponse non 2xx), l’appel reste visible dans l’historique avec le code et le corps de la réponse.

Exemple d’endpoint (Python/Flask)

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/jobaffinity/<token>', methods=['POST'])
def handle_webhook(token):
    if token != 'votre-jeton-secret':
        return '', 404

    data = request.json
    application_path = data['_self']

    response = requests.get(
        f'https://jobaffinity.fr{application_path}',
        auth=('login', 'password')
    )
    process_application_change(response.json())

    return jsonify({'status': 'received'}), 200

def process_application_change(application):
    # Votre logique métier ici
    pass

Exemple d’endpoint (Node.js/Express)

const express = require('express');
const axios = require('axios');

const app = express();
app.use(express.json());

app.post('/webhook/jobaffinity/:token', async (req, res) => {
  if (req.params.token !== 'votre-jeton-secret') {
    return res.sendStatus(404);
  }

  res.status(200).json({ status: 'received' });

  try {
    const response = await axios.get(
      `https://jobaffinity.fr${req.body._self}`,
      { auth: { username: 'login', password: 'password' } }
    );
    await processApplicationChange(response.data);
  } catch (error) {
    console.error('Error processing webhook:', error);
  }
});

async function processApplicationChange(application) {
  // Votre logique métier
}

app.listen(3000);

Monitoring

Utilisez l’historique des webhooks pour vérifier que votre endpoint répond correctement, déboguer les erreurs et auditer les notifications reçues. Un response_status à 0 signifie que votre endpoint n’a pas pu être joint ; response_body contient alors le message d’erreur.

Gestion des versions

Les webhooks suivent le même principe de versioning que l’API REST. En cas de changement majeur dans le format des webhooks, vous serez notifié à l’avance.

Introduction

Démarrage

Architecture de l'API

Webhooks

Introduction aux Webhooks

Événements disponibles

Configuration

Format de la notification

Historique des appels Webhook

Requête

Réponse

Champs de la réponse

Implémentation d’un endpoint

Bonnes pratiques

Exemple d’endpoint (Python/Flask)

Exemple d’endpoint (Node.js/Express)

Monitoring

Gestion des versions

​Introduction aux Webhooks

​Événements disponibles

​Configuration

​Format de la notification

​Historique des appels Webhook

​Requête

​Réponse

​Champs de la réponse

​Implémentation d’un endpoint

​Bonnes pratiques

​Exemple d’endpoint (Python/Flask)

​Exemple d’endpoint (Node.js/Express)

​Monitoring

​Gestion des versions

Introduction aux Webhooks

Événements disponibles

Configuration

Format de la notification

Historique des appels Webhook

Requête

Réponse

Champs de la réponse

Implémentation d’un endpoint

Bonnes pratiques

Exemple d’endpoint (Python/Flask)

Exemple d’endpoint (Node.js/Express)

Monitoring

Gestion des versions