Introduction aux Webhooks
Les webhooks permettent à JobAffinity de notifier votre système en temps réel lors d’événements importants (nouvelle candidature, changement d’étape, etc.).
Événements disponibles
Les principaux événements webhook sont :
ProcessStepChange : Changement d’étape dans le processus d’une candidature- Autres événements disponibles (contactez le support pour la liste complète)
Configuration
Pour configurer les webhooks, contactez le support d’Intuition-Software : [email protected]
Vous devrez fournir :
- L’URL de votre endpoint qui recevra les notifications
- Les événements auxquels vous souhaitez souscrire
- Les méthodes de sécurité souhaitées (authentification, signature, etc.)
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": [
{
"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
event : Type d’événement déclenchédatetime : Date et heure de l’appel webhookresponse_status : Code de statut HTTP retourné par votre endpointresponse_body : Corps de la réponse de votre endpointapplication : 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 : Votre endpoint doit répondre en moins de 30 secondes
- Retournez un code 200 : Même si le traitement est asynchrone
- Validez les données : Vérifiez l’authenticité et la structure des données reçues
- Gérez les doublons : Un même événement peut être envoyé plusieurs fois en cas d’échec
- Loggez les appels : Conservez une trace des webhooks reçus pour le débogage
Exemple d’endpoint (Python/Flask)
from flask import Flask, request, jsonify
import requests
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def handle_webhook():
# Récupérer les données du webhook
data = request.json
event_type = data.get('event')
# Traiter selon le type d'événement
if event_type == 'ProcessStepChange':
application_url = data.get('application', {}).get('_self')
# Récupérer les détails complets via l'API
response = requests.get(
f'https://jobaffinity.fr{application_url}',
auth=('login', 'password')
)
application_details = response.json()
# Votre logique métier ici
process_application_change(application_details)
# Répondre rapidement
return jsonify({'status': 'received'}), 200
def process_application_change(application):
# Traitement asynchrone
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', async (req, res) => {
const { event, application } = req.body;
// Répondre immédiatement
res.status(200).json({ status: 'received' });
// Traitement asynchrone
if (event === 'ProcessStepChange') {
try {
const response = await axios.get(
`https://jobaffinity.fr${application._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
- Détecter les problèmes de performance
- Auditer les événements reçus
Si votre endpoint retourne régulièrement des erreurs (5xx), les appels webhook peuvent être temporairement suspendus. Surveillez votre historique et corrigez les problèmes rapidement.
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.