Webhooks

Introduction to Webhooks

Webhooks allow JobAffinity to notify your system when an application changes step. Notifications are sent in batches, within minutes of the change.

Available Events

The ProcessStepChange event is emitted each time an application changes step. If you need other events, let support know.

Configuration

To enable webhooks, contact Intuition-Software support: support@intuition-software.fr, providing the HTTPS URL of your endpoint. A single URL is configured per organisation. The notification body contains no personal data: only identifiers and links to the REST API. We recommend including an unguessable secret token in the URL (for example https://example.com/webhook/jobaffinity/7f3a9c2e...) and rejecting any call that does not carry it. If you have other needs (call authentication, signature, additional events), let support know.

Notification Format

JobAffinity sends a POST request with a JSON body:

{
  "_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: paths to prefix with https://jobaffinity.fr to fetch details via the REST API
id, candidate.id, job.id: identifiers of the application, the candidate and the job
step.name: name of the current step
step.status: position of the step in the process: START (first step), CURRENT (intermediate step) or END (final step)
step.date: date the application entered the step, in YYYY-MM-DD HH:MM:SS format

The notification describes the state of the application at the time it is sent. If an application changes step several times before the notification is sent, a single notification is emitted, carrying the latest step. Treat each notification as a signal that “this application has changed” and re-read its state via the API, rather than as an event log.

Webhook Call History

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

Request

GET /restapi/v1/webhook/task

Response

{
  "_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"
      }
    }
  ]
}

Response Fields

id: identifier of the call, used for pagination
event: Type of triggered event
datetime: Date and time of the webhook call
response_status: HTTP status code returned by your endpoint, or 0 if the endpoint could not be reached (the error message is then in response_body)
response_body: Response body from your endpoint
application: Reference to the related application

This resource is paginated. Use the _next field to browse the complete history.

Implementing an Endpoint

Best Practices

Respond quickly: Acknowledge the request, then process it asynchronously
Return a 2xx code: The code and the first 1024 characters of your response are kept in the history
Check the token: Reject calls that do not carry your secret token
Make processing idempotent: Re-read the current state of the application via the API on each notification
Log calls: Keep a record of received webhooks for debugging

Each notification is sent once. On failure (network error, non-2xx response), the call remains visible in the history with the response code and body.

Endpoint Example (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 != 'your-secret-token':
        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):
    # Your business logic here
    pass

Endpoint Example (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 !== 'your-secret-token') {
    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) {
  // Your business logic
}

app.listen(3000);

Monitoring

Use the webhook history to verify that your endpoint responds correctly, debug errors and audit received notifications. A response_status of 0 means your endpoint could not be reached; response_body then contains the error message.

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.

Introduction

Getting Started

API Architecture

Webhooks

Introduction to Webhooks

Available Events

Configuration

Notification Format

Webhook Call History

Request

Response

Response Fields

Implementing an Endpoint

Best Practices

Endpoint Example (Python/Flask)

Endpoint Example (Node.js/Express)

Monitoring

Version Management

​Introduction to Webhooks

​Available Events

​Configuration

​Notification Format

​Webhook Call History

​Request

​Response

​Response Fields

​Implementing an Endpoint

​Best Practices

​Endpoint Example (Python/Flask)

​Endpoint Example (Node.js/Express)

​Monitoring

​Version Management

Introduction to Webhooks

Available Events

Configuration

Notification Format

Webhook Call History

Request

Response

Response Fields

Implementing an Endpoint

Best Practices

Endpoint Example (Python/Flask)

Endpoint Example (Node.js/Express)

Monitoring

Version Management