Skip to main content

​
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: [email protected] 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

GET /restapi/v1/webhook/task

​
Response

{
  "_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
This resource is paginated. Use the _next field to browse the complete history.

​
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)

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)

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
If your endpoint regularly returns errors (5xx), webhook calls may be temporarily suspended. Monitor your history and fix issues quickly.

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