Skip to content

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 ​

TypeDescription
enrichment.completedUn enrichissement s'est terminé avec succès
enrichment.failedUn 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 :

HeaderDescription
X-Webhook-SignatureSignature HMAC SHA256 au format sha256=<hex>
X-Webhook-EventType de l'événement (ex : enrichment.completed)
X-Webhook-IdIdentifiant unique de l'événement
X-Webhook-TimestampHorodatage 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 :

TentativeDélai
130 secondes
21 minute
32 minutes
44 minutes
58 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 ​

NomTypeRequisDescription
x-access-tokenStringouiClé API

Réponses ​

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

WARNING

Le secret n'est jamais renvoyé par cette liste. Il n'est exposé qu'une seule fois, à la création du webhook (POST /v1/webhook) et lorsqu'il est régénéré suite à un changement d'URL (PUT /v1/webhook/:id). Conservez-le à ce moment-là.

:::


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 ​

NomTypeRequisDescription
x-access-tokenStringouiClé API

Body (JSON) ​

NomTypeRequisDescription
eventTypeStringouiType d'événement : enrichment.completed ou enrichment.failed
urlStringouiURL 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 ​

NomTypeRequisDescription
idintouiIdentifiant du webhook (idWebhookConfig)

Headers ​

NomTypeRequisDescription
x-access-tokenStringouiClé API

Body (JSON) ​

NomTypeRequisDescription
urlStringnonNouvelle URL de réception (HTTPS obligatoire)
isActivebooleannonActiver 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 ​

NomTypeRequisDescription
idintouiIdentifiant du webhook (idWebhookConfig)

Headers ​

NomTypeRequisDescription
x-access-tokenStringouiClé 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 ​

NomTypeRequisDescription
idintouiIdentifiant du webhook (idWebhookConfig)

Headers ​

NomTypeRequisDescription
x-access-tokenStringouiClé 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 ​

NomTypeRequisDescription
x-access-tokenStringouiClé API

Paramètres query ​

NomTypeRequisDescription
eventTypeStringnonFiltrer par type d'événement
statusStringnonFiltrer par statut : PENDING, SENDING, SUCCESS, RETRY, FAILED
limitintnonNombre 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

Coefficy — API externe