Webhooks

Restez synchronisé sans interroger l'API en boucle. Chaque livraison est signée HMAC-SHA256 dans l'en-tête X-Karaba-Signature, dérivée du secret affiché une seule fois à la création.

POST/v1/webhookswebhook:write

Enregistre un endpoint et ses événements

Requête

{
  "url": "https://votre-systeme.com/hooks/karaba",
  "events": [
    "job.broadcast.completed",
    "job.candidate_replied"
  ]
}

Réponse

{
  "id": 7,
  "url": "https://votre-systeme.com/hooks/karaba",
  "events": [
    "job.broadcast.completed",
    "job.candidate_replied"
  ],
  "signing_secret": "a1b2c3d4e5f60718293a4b5c6d7e8f90"
}

GET/v1/webhookswebhook:write

Liste vos endpoints enregistrés

Réponse

[
  {
    "id": 7,
    "url": "https://votre-systeme.com/hooks/karaba",
    "events": [
      "job.broadcast.completed",
      "job.candidate_replied"
    ],
    "is_active": true
  }
]

DELETE/v1/webhooks/{id}webhook:write

Supprime un endpoint

Réponse

204 No Content

Événements disponibles

match.completed

Une requête /v1/match/query a terminé son traitement.

profile.ready

Un profil ingéré via /v1/profiles/cv a fini son extraction IA.

trust.scored

Un Trust Score vient d'être calculé.

job.broadcast.completed

Une diffusion WhatsApp a fini d'envoyer tous ses messages.

job.candidate_replied

Un candidat a répondu intéressé ou pas à une diffusion.

Vérifier la signature

Chaque livraison porte un en-tête X-Karaba-Signature : HMAC-SHA256 du corps brut, signé avec la clé affichée une seule fois à l'enregistrement du webhook (jamais le secret en clair par la suite).

import hashlib, hmac

def verify(body: bytes, signature: str, signing_key: str) -> bool:
    expected = hmac.new(signing_key.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)