Webhooks

Permet de configurer des webhooks pour recevoir des notifications automatiques lorsque certains événements se produisent (ex : enrichissement terminé ou échoué).

Fonctionnement général

Les webhooks sont configurés au niveau du compte. Lorsqu'un événement se produit, Coefficy envoie une requête HTTP POST vers l'URL configurée avec le payload de l'événement.

Types d'événements

Type	Description
`enrichment.completed`	Un enrichissement s'est terminé avec succès
`enrichment.failed`	Un enrichissement a échoué

Signature

Chaque webhook est signé avec un secret unique (généré automatiquement à la création). La signature est envoyée dans les headers HTTP.

Headers envoyés :

Header	Description
`X-Webhook-Signature`	Signature HMAC SHA256 au format `sha256=<hex>`
`X-Webhook-Event`	Type de l'événement (ex : `enrichment.completed`)
`X-Webhook-Id`	Identifiant unique de l'événement
`X-Webhook-Timestamp`	Horodatage ISO 8601 de l'envoi

Vérification côté client :

javascript

const crypto = require('crypto');

const timestamp = req.headers['x-webhook-timestamp'];
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);

const expected = 'sha256=' + crypto
  .createHmac('sha256', webhookSecret)
  .update(timestamp + '.' + payload)
  .digest('hex');

const isValid = signature === expected;

Retry

En cas d'échec (HTTP >= 400 ou timeout de 10 secondes), jusqu'à 5 tentatives sont effectuées avec un backoff exponentiel :

Tentative	Délai
1	30 secondes
2	1 minute
3	2 minutes
4	4 minutes
5	8 minutes

Après 5 échecs consécutifs, l'événement passe en statut FAILED.

Payload

json

{
    "test": false,
    "idProcessAction": 12345,
    "enrichmentType": "phone",
    "status": "completed",
    "timestamp": "2026-03-25T14:30:00.000Z",
    "idCrmVisitCard": 67890,
    "result": {
        "firstName": "Jean",
        "lastName": "Dupont",
        "email": "jean.dupont@example.com",
        "phone": "+33612345678",
        "mobile": null,
        "linkedinUrl": null
    }
}

Lister les webhooks

GET /v1/webhook

Retourne la liste des configurations webhook du compte.

Headers

Nom	Type	Requis	Description
x-access-token	String	oui	Clé API

Réponses

200 — OK

json

{
    "success": true,
    "code": "200",
    "message": "OK",
    "result": [
        {
            "idWebhookConfig": "int",
            "idAccount": "string",
            "eventType": "string",
            "url": "string",
            "secret": "string",
            "isActive": "boolean",
            "created": "datetime",
            "modified": "datetime"
        }
    ]
}

Créer un webhook

POST /v1/webhook

Crée une nouvelle configuration webhook. Un secret est automatiquement généré et retourné dans la réponse.

WARNING

Un seul webhook par type d'événement est autorisé par compte.

Headers

Nom	Type	Requis	Description
x-access-token	String	oui	Clé API

Body (JSON)

Nom	Type	Requis	Description
eventType	String	oui	Type d'événement : `enrichment.completed` ou `enrichment.failed`
url	String	oui	URL de réception (HTTPS obligatoire)

Réponses

200 — Webhook créé

json

{
    "success": true,
    "code": "200",
    "message": "Webhook créé",
    "parameters": {
        "eventType": "string",
        "url": "string"
    },
    "result": {
        "idWebhookConfig": "int",
        "idAccount": "string",
        "eventType": "string",
        "url": "string",
        "secret": "string",
        "isActive": "boolean",
        "created": "datetime"
    }
}

TIP

Conservez le secret retourné : il est nécessaire pour vérifier la signature des webhooks reçus.

400 — Bad Request

json

{
    "success": false,
    "code": "400",
    "message": "Le paramètre eventType est requis"
}

Retourné si :

Le paramètre eventType est manquant ou invalide
Le paramètre url est manquant ou n'utilise pas HTTPS
Un webhook existe déjà pour ce type d'événement sur ce compte

Modifier un webhook

PUT /v1/webhook/:id

Met à jour une configuration webhook existante.

WARNING

Si l'URL est modifiée, un nouveau secret est automatiquement généré. L'ancien secret devient invalide.

Paramètres URL

Nom	Type	Requis	Description
id	int	oui	Identifiant du webhook (idWebhookConfig)

Headers

Nom	Type	Requis	Description
x-access-token	String	oui	Clé API

Body (JSON)

Nom	Type	Requis	Description
url	String	non	Nouvelle URL de réception (HTTPS obligatoire)
isActive	boolean	non	Activer ou désactiver le webhook

Réponses

200 — Webhook mis à jour

json

{
    "success": true,
    "code": "200",
    "message": "Webhook mis à jour",
    "parameters": {
        "idWebhookConfig": "int"
    },
    "result": {
        "idWebhookConfig": "int",
        "idAccount": "string",
        "eventType": "string",
        "url": "string",
        "secret": "string (uniquement si l'URL a changé)",
        "isActive": "boolean",
        "modified": "datetime"
    }
}

400 — Bad Request

json

{
    "success": false,
    "code": "400",
    "message": "URL invalide"
}

403 — Forbidden

json

{
    "success": false,
    "code": "403",
    "message": "L'utilisateur n'a pas accès à ce webhook"
}

404 — Not Found

json

{
    "success": false,
    "code": "404",
    "message": "Webhook introuvable"
}

Supprimer un webhook

DELETE /v1/webhook/:id

Supprime une configuration webhook. Les événements déjà envoyés sont conservés dans l'historique.

Paramètres URL

Nom	Type	Requis	Description
id	int	oui	Identifiant du webhook (idWebhookConfig)

Headers

Nom	Type	Requis	Description
x-access-token	String	oui	Clé API

Réponses

200 — Webhook supprimé

json

{
    "success": true,
    "code": "200",
    "message": "Webhook supprimé",
    "parameters": {
        "idWebhookConfig": "int"
    }
}

403 — Forbidden

json

{
    "success": false,
    "code": "403",
    "message": "L'utilisateur n'a pas accès à ce webhook"
}

404 — Not Found

json

{
    "success": false,
    "code": "404",
    "message": "Webhook introuvable"
}

Tester un webhook

POST /v1/webhook/:id/test

Envoie un webhook de test à l'URL configurée avec un payload fictif. Permet de vérifier que votre endpoint reçoit et valide correctement les webhooks.

Paramètres URL

Nom	Type	Requis	Description
id	int	oui	Identifiant du webhook (idWebhookConfig)

Headers

Nom	Type	Requis	Description
x-access-token	String	oui	Clé API

Réponses

200 — Webhook de test envoyé

json

{
    "success": true,
    "code": "200",
    "message": "Webhook de test envoyé",
    "parameters": {
        "idWebhookConfig": "int"
    },
    "result": {
        "idWebhookEvent": "int",
        "status": "string",
        "httpStatus": "int",
        "responseBody": "string"
    }
}

status : SUCCESS si votre endpoint a répondu HTTP 2xx, FAILED sinon
httpStatus : code HTTP retourné par votre endpoint
responseBody : corps de la réponse (tronqué à 1000 caractères)

400 — Bad Request

json

{
    "success": false,
    "code": "400",
    "message": "Impossible de créer l'événement webhook (config inactive ?)"
}

Retourné si le webhook est désactivé (isActive: false).

403 — Forbidden

json

{
    "success": false,
    "code": "403",
    "message": "L'utilisateur n'a pas accès à ce webhook"
}

404 — Not Found

json

{
    "success": false,
    "code": "404",
    "message": "Webhook introuvable"
}

Historique des événements

GET /v1/webhook/events

Retourne l'historique des événements webhook envoyés pour le compte.

Headers

Nom	Type	Requis	Description
x-access-token	String	oui	Clé API

Paramètres query

Nom	Type	Requis	Description
eventType	String	non	Filtrer par type d'événement
status	String	non	Filtrer par statut : `PENDING`, `SENDING`, `SUCCESS`, `RETRY`, `FAILED`
limit	int	non	Nombre de résultats (défaut : 50)

Réponses

200 — OK

json

{
    "success": true,
    "code": "200",
    "message": "OK",
    "parameters": {
        "eventType": "string|null",
        "status": "string|null",
        "limit": "int"
    },
    "result": [
        {
            "idWebhookEvent": "int",
            "idWebhookConfig": "int",
            "idAccount": "string",
            "eventType": "string",
            "payload": "object",
            "status": "string",
            "httpStatus": "int|null",
            "responseBody": "string|null",
            "retryCount": "int",
            "maxRetries": "int",
            "nextRetryDate": "datetime|null",
            "lastAttemptDate": "datetime|null",
            "created": "datetime",
            "modified": "datetime"
        }
    ]
}

Statuts possibles :

PENDING — En attente d'envoi
SENDING — En cours d'envoi
SUCCESS — Envoyé avec succès
RETRY — Échec, nouvelle tentative planifiée
FAILED — Échec définitif après toutes les tentatives

Webhooks ​

Fonctionnement général ​

Types d'événements ​

Signature ​

Retry ​

Payload ​

Lister les webhooks ​

Headers ​

Réponses ​

Créer un webhook ​

Headers ​

Body (JSON) ​

Réponses ​

Modifier un webhook ​

Paramètres URL ​

Headers ​

Body (JSON) ​

Réponses ​

Supprimer un webhook ​

Paramètres URL ​

Headers ​

Réponses ​

Tester un webhook ​

Paramètres URL ​

Headers ​

Réponses ​

Historique des événements ​

Headers ​

Paramètres query ​

Réponses ​

Webhooks

Fonctionnement général

Types d'événements

Signature

Retry

Payload

Lister les webhooks

Headers

Réponses

Créer un webhook

Headers

Body (JSON)

Réponses

Modifier un webhook

Paramètres URL

Headers

Body (JSON)

Réponses

Supprimer un webhook

Paramètres URL

Headers

Réponses

Tester un webhook

Paramètres URL

Headers

Réponses

Historique des événements

Headers

Paramètres query

Réponses