> ## 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 and usage of webhooks for real-time notifications

## Introduction to Webhooks

Webhooks allow JobAffinity to notify your system in real-time during important events (new application, step change, etc.).

## Available Events

Main webhook events include:

* **`ProcessStepChange`**: Step change in an application process
* Other events available (contact support for the complete list)

## Configuration

To configure webhooks, contact Intuition-Software support: [support@intuition-software.fr](mailto:support@intuition-software.fr)

You will need to provide:

* Your endpoint URL that will receive notifications
* The events you want to subscribe to
* Desired security methods (authentication, signature, etc.)

## Webhook Call History

You can view the history of webhook calls made by JobAffinity.

### Request

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

### Response

```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"
      }
    }
  ]
}
```

### Response Fields

* **`event`**: Type of triggered event
* **`datetime`**: Date and time of the webhook call
* **`response_status`**: HTTP status code returned by your endpoint
* **`response_body`**: Response body from your endpoint
* **`application`**: Reference to the related application

<Note>
  This resource is paginated. Use the `_next` field to browse the complete history.
</Note>

## Implementing an Endpoint

### Best Practices

1. **Respond quickly**: Your endpoint must respond in less than 30 seconds
2. **Return a 200 code**: Even if processing is asynchronous
3. **Validate data**: Verify authenticity and data structure
4. **Handle duplicates**: The same event may be sent multiple times in case of failure
5. **Log calls**: Keep a record of received webhooks for debugging

### Endpoint Example (Python/Flask)

```python theme={null}
from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    # Get webhook data
    data = request.json
    event_type = data.get('event')

    # Process by event type
    if event_type == 'ProcessStepChange':
        application_url = data.get('application', {}).get('_self')

        # Fetch complete details via API
        response = requests.get(
            f'https://jobaffinity.fr{application_url}',
            auth=('login', 'password')
        )

        application_details = response.json()

        # Your business logic here
        process_application_change(application_details)

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

def process_application_change(application):
    # Asynchronous processing
    pass
```

### Endpoint Example (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;

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

  // Asynchronous processing
  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) {
  // Your business logic
}

app.listen(3000);
```

## Monitoring

Use webhook history to:

* Verify your endpoint responds correctly
* Debug errors
* Detect performance issues
* Audit received events

<Warning>
  If your endpoint regularly returns errors (5xx), webhook calls may be temporarily suspended. Monitor your history and fix issues quickly.
</Warning>

## Version Management

Webhooks follow the same versioning principle as the REST API. In case of major changes to the webhook format, you will be notified in advance.