Webhooks API

Les webhooks vous permettent de recevoir des notifications HTTP en temps réel lorsque des événements se produisent dans votre compte NERP Suite (nouvelle commande, stock bas, etc.).

Fonctionnement

1. Vous enregistrez une URL HTTPS et les événements qui vous intéressent
2. Quand un événement se produit, NERP Suite envoie un POST à votre URL
3. Le payload est signé avec HMAC SHA-256 pour vérifier l'authenticité

Headers envoyés

Vérification de la signature

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

---

Événements disponibles

GET /v1/public-api/webhooks/events

Scope requis: read:webhooks

Événements supportés

---

Lister les webhooks

GET /v1/public-api/webhooks

Scope requis: read:webhooks

Paramètres de requête

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/webhooks" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "data": [
    {
      "id": "wh_001",
      "url": "https://example.com/webhooks/nerpsuite",
      "events": ["order.created", "stock.low-alert"],
      "isActive": true,
      "description": "Notifications commandes et stock",
      "lastTriggeredAt": "2024-01-25T14:30:00Z",
      "lastStatusCode": 200,
      "failureCount": 0,
      "createdAt": "2024-01-01T10:00:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

---

Obtenir un webhook

GET /v1/public-api/webhooks/:id

Scope requis: read:webhooks

---

Consulter les logs de livraison

GET /v1/public-api/webhooks/:id/logs

Scope requis: read:webhooks

Paramètres de requête

Réponse

{
  "data": [
    {
      "id": "whl_001",
      "event": "order.created",
      "statusCode": 200,
      "success": true,
      "error": null,
      "duration": 145,
      "createdAt": "2024-01-25T14:30:00Z"
    },
    {
      "id": "whl_002",
      "event": "stock.low-alert",
      "statusCode": 500,
      "success": false,
      "error": "HTTP 500",
      "duration": 2034,
      "createdAt": "2024-01-25T12:15:00Z"
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 20,
  "totalPages": 3
}

---

Créer un webhook

POST /v1/public-api/webhooks

Scope requis: write:webhooks

Corps de la requête

Exemple de requête

curl -X POST "https://api.nerpsuite.com/v1/public-api/webhooks" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/nerpsuite",
    "events": ["order.created", "stock.low-alert", "supplier-order.status-changed"],
    "description": "Notifications pour mon ERP"
  }'

Réponse

{
  "id": "wh_001",
  "url": "https://example.com/webhooks/nerpsuite",
  "events": ["order.created", "stock.low-alert", "supplier-order.status-changed"],
  "isActive": true,
  "description": "Notifications pour mon ERP",
  "secret": "a1b2c3d4e5f6...your_webhook_secret",
  "failureCount": 0,
  "createdAt": "2024-01-25T10:00:00Z"
}

Important : Le secret n'est retourné qu'une seule fois lors de la création. Conservez-le précieusement pour vérifier les signatures.

---

Mettre à jour un webhook

PATCH /v1/public-api/webhooks/:id

Scope requis: write:webhooks

Corps de la requête

Tous les champs sont optionnels.

Exemple : Désactiver un webhook

curl -X PATCH "https://api.nerpsuite.com/v1/public-api/webhooks/wh_001" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

---

Supprimer un webhook

DELETE /v1/public-api/webhooks/:id

Scope requis: write:webhooks

Exemple de requête

curl -X DELETE "https://api.nerpsuite.com/v1/public-api/webhooks/wh_001" \
  -H "X-API-Key: sk_live_xxx"

Retourne 204 No Content en cas de succès.

---

Champs de réponse

Webhook

Log de livraison

Payload d'un webhook

Chaque appel webhook envoie un body JSON avec cette structure :

{
  "event": "order.created",
  "timestamp": "2024-01-25T14:30:00.000Z",
  "data": {
    "companyId": "comp_001",
    "order": {
      "id": "ord_123",
      "orderNumber": "ORD-2024-000456"
    }
  }
}

Le contenu de data varie selon l'événement.

Cas d'usage

Notification Slack sur stock bas

// Votre serveur reçoit le webhook
app.post('/webhooks/nerpsuite', (req, res) => {
  const { event, data } = req.body;

  if (event === 'stock.low-alert') {
    slack.send({
      text: `Alerte stock bas : ${data.productName} (${data.quantity} restants)`
    });
  }

  res.sendStatus(200);
});

Synchronisation ERP sur nouvelles commandes

app.post('/webhooks/nerpsuite', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'order.created') {
    await erp.createSalesOrder({
      reference: data.order.orderNumber,
      customer: data.order.customerId,
      items: data.order.items
    });
  }

  res.sendStatus(200);
});