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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.