> ## Documentation Index
> Fetch the complete documentation index at: https://api.jobaffinity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Configuration et utilisation des webhooks pour recevoir des notifications en temps réel

## 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 : [support@intuition-software.fr](mailto:support@intuition-software.fr)

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

```bash theme={null}
GET /restapi/v1/webhook/task
```

### Réponse

```json theme={null}
{
  "_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 webhook
* **`response_status`** : Code de statut HTTP retourné par votre endpoint
* **`response_body`** : Corps de la réponse de votre endpoint
* **`application`** : Référence à la candidature concernée

<Note>
  Cette ressource est paginée. Utilisez le champ `_next` pour parcourir l'historique complet.
</Note>

## Implémentation d'un endpoint

### Bonnes pratiques

1. **Répondez rapidement** : Votre endpoint doit répondre en moins de 30 secondes
2. **Retournez un code 200** : Même si le traitement est asynchrone
3. **Validez les données** : Vérifiez l'authenticité et la structure des données reçues
4. **Gérez les doublons** : Un même événement peut être envoyé plusieurs fois en cas d'échec
5. **Loggez les appels** : Conservez une trace des webhooks reçus pour le débogage

### Exemple d'endpoint (Python/Flask)

```python theme={null}
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)

```javascript theme={null}
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

<Warning>
  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.
</Warning>

## 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.