Comment paramétrer un webhook ?

Introduction

Un webhook prévient automatiquement une application tierce (Make, Zapier, n8n, votre propre service…) dès qu'un évènement se produit dans Atimeüs. Atimeüs envoie alors une requête HTTP POST contenant les données de l'évènement vers une URL que vous choisissez.

Contrairement à l'API, où votre application doit interroger Atimeüs régulièrement, c'est Atimeüs qui vous appelle.

Liste des déclencheurs

Les entités suivantes déclenchent un webhook à leur création (created), leur mise à jour (updated) et leur suppression (deleted). Le déclencheur s'écrit entité.évènement, par exemple project.created.

• Collaborateur (employee)
• Projet (project)
• Tâche d'un projet (project-task)
• Contrat (contract)
• Facture (invoice)
• Client (customer)
• Fournisseur (subcontractor)
• Contact (contact)
• Opportunité (opportunity)
• Candidat (candidate)
• Candidature (application)
• Tâche d'un utilisateur (user-task)

Il existe aussi des évènements métier :

• Projet synchronisé (project.synced)
• Facture validée (invoice.validated)
• Devis validé (quotes.validated)
• Opportunité gagnée (opportunity.won) ou perdue (opportunity.lost)
• Candidature gagnée (application.won) ou perdue (application.lost)
• Mois clôturé (month.closed)
• CRA complété par le collaborateur (timesheet.completed)
• CRA validé par le manager (timesheet.validated)
• CRA clôturé (timesheet.closed)
• CRA déverrouillé (timesheet.unlocked)

Paramétrer un webhook

Prérequis : avoir le droit Webhooks, et avoir créé au préalable l'URL de réception (scénario Make, Zap Zapier, endpoint de votre application…).

1. Ouvrir Configuration > Externes > Webhooks.
2. Remplir le formulaire Nouveau webhook :
   • Nom : libellé qui sert à retrouver le webhook dans la liste ;
   • URL : adresse à laquelle les données seront envoyées ;
   • Secret (facultatif, mais recommandé) : clé qui sert à signer les envois, voir Sécuriser les appels ci-dessous ;
   • Déclencheur(s) : un ou plusieurs évènements à surveiller.
3. Cliquer sur Enregistrer.

Le webhook est actif dès sa création. Dans la liste, la colonne Actif ? permet de le suspendre, et la colonne Dernier appel affiche le code HTTP renvoyé par votre URL lors du dernier envoi.

Données envoyées

Chaque envoi est une requête POST au format JSON (UTF-8). Le corps contient toujours :

• trigger : le déclencheur, par exemple project.updated ;
• date : la date de l'évènement, en UTC, au format yyyy-MM-ddTHH:mm:ss.

Il contient ensuite, selon le déclencheur :

Les entités envoyées dans data, from et to ont le même contenu que leur lecture par l'API (champs personnalisés compris).

Exemple :

{
    "trigger": "subcontractor.updated",
    "date": "2026-10-02T13:17:37",
    "from": {
        "id": "ddd46cc6-ea8d-49a8-9d1a-451eac8e6a15",
        "name": "NOVACONSULTO",
        "description": null,
        ...
        "updateDate": "2026-10-02T13:14:33.703",
        "updateAuthor": "jean.dupont@exemple.fr"
    },
    "to": {
        "id": "ddd46cc6-ea8d-49a8-9d1a-451eac8e6a15",
        "name": "NOVACONSULTO",
        "description": "Fournisseur de prestations réseau",
        ...
        "updateDate": "2026-10-02T13:17:37.167",
        "updateAuthor": "jean.dupont@exemple.fr"
    }
}

Sécuriser les appels

Chaque appel porte l'en-tête X-Atimeus-Webhook-Date (date d'envoi, en UTC). Si un secret est renseigné sur le webhook, Atimeüs ajoute l'en-tête X-Atimeus-Webhook-Signature, qui permet de vérifier que l'appel vient bien d'Atimeüs.

Pour vérifier la signature :

1. construire la chaîne date:corps, où date est la valeur de l'en-tête X-Atimeus-Webhook-Date et corps le contenu brut de la requête ;
2. calculer le HMAC SHA-256 de cette chaîne avec le secret comme clé ;
3. encoder le résultat en Base64 et le comparer à l'en-tête X-Atimeus-Webhook-Signature.

var s = $"{date}:{payload}";
var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var hash = hmacsha256.ComputeHash(Encoding.UTF8.GetBytes(s));
var signature = Convert.ToBase64String(hash);

Trois pièges à éviter :

• utiliser la date de l'en-tête, et non la propriété date du corps : elles diffèrent dès qu'un envoi est retenté ;
• calculer la signature sur le corps brut, avant toute désérialisation : un JSON réindenté donne une autre signature ;
• la signature est en Base64, pas en hexadécimal, et sans préfixe sha256=.

Cas de Make : pour une URL Make (make.com), le secret est envoyé dans l'en-tête x-make-apikey au lieu de la signature. Renseignez la même clé dans la protection par clé d'API du webhook Make.

Échecs et nouvelles tentatives

• Un envoi est réussi si votre URL répond par un code 2xx. Toute autre réponse, ou l'absence de réponse, est un échec.
• En cas d'échec, Atimeüs retente l'envoi, jusqu'à 5 tentatives au total, avec un délai qui double à chaque fois. Au-delà, l'évènement est abandonné.
• Un même évènement peut arriver plusieurs fois. Votre traitement doit donc supporter les doublons, par exemple en ignorant un évènement déjà traité.

Pour aller plus loin (gestion des webhooks par l'API, exemples de chaque format) : documentation développeur des webhooks.