Skip to Content
Référence de l'APIWebhooks

Webhooks (Réception)

Lorsque des événements se produisent dans votre projet SupDesk, les webhooks sortants envoient des requêtes HTTP POST à vos endpoints configurés. Cette page documente le format du payload, le mécanisme de signature et le comportement de nouvelles tentatives afin que vous puissiez construire des récepteurs de webhooks fiables.

Format du payload

Chaque livraison de webhook utilise une enveloppe standard :

{
  "event": "post.created",
  "timestamp": "2026-07-15T12:00:00.000Z",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": { ... }
}
ChampTypeDescription
eventstringL’événement qui a déclenché la livraison
timestampstringHorodatage ISO 8601 de la production de l’événement
project_idstringUUID du projet où l’événement s’est produit
dataobjectPayload spécifique à l’événement (voir ci-dessous)

Événements

post.created

Un nouveau post de feedback a été soumis.

{
  "event": "post.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Add dark mode",
    "type": "feature",
    "status": "open",
    "author_type": "end_user",
    "body": "It would be great to have a dark mode option.",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

post.updated

Un post de feedback a été modifié.

{
  "event": "post.updated",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Add dark mode",
    "type": "feature",
    "status": "open",
    "author_type": "end_user",
    "body": "It would be great to have a dark mode option.",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

post.deleted

Un post de feedback a été supprimé.

{
  "event": "post.deleted",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Add dark mode",
    "type": "feature",
    "status": "open",
    "author_type": "end_user",
    "body": "It would be great to have a dark mode option.",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

post.status_changed

Le statut d’un post a été modifié.

{
  "event": "post.status_changed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Add dark mode",
    "type": "feature",
    "old_status": "open",
    "new_status": "planned",
    "author_type": "member",
    "body": "We're planning this for Q3.",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

comment.created

Un nouveau commentaire a été ajouté à un post.

{
  "event": "comment.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "post_id": "550e8400-e29b-41d4-a716-446655440001",
    "post_title": "Add dark mode",
    "author_type": "end_user",
    "body": "Any update on this?",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

comment.updated

Un commentaire a été modifié.

{
  "event": "comment.updated",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "post_id": "550e8400-e29b-41d4-a716-446655440001",
    "post_title": "Add dark mode",
    "author_type": "end_user",
    "body": "Any update on this?",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

comment.deleted

Un commentaire a été supprimé.

{
  "event": "comment.deleted",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "post_id": "550e8400-e29b-41d4-a716-446655440001",
    "post_title": "Add dark mode",
    "author_type": "end_user",
    "body": "Any update on this?",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

message.created

Un nouveau message privé a été envoyé.

{
  "event": "message.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "thread_id": "550e8400-e29b-41d4-a716-446655440001",
    "thread_subject": "Help needed",
    "sender": "end_user",
    "body": "I can't find the settings page.",
    "via": "web",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

message.updated

Un message privé a été modifié.

{
  "event": "message.updated",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "thread_id": "550e8400-e29b-41d4-a716-446655440001",
    "thread_subject": "Help needed",
    "sender": "end_user",
    "body": "I can't find the settings page.",
    "via": "web",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

message.deleted

Un message privé a été supprimé.

{
  "event": "message.deleted",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "thread_id": "550e8400-e29b-41d4-a716-446655440001",
    "thread_subject": "Help needed",
    "sender": "end_user",
    "body": "I can't find the settings page.",
    "via": "web",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

beta_feedback.created

Un testeur bêta a envoyé un retour sur un programme bêta.

{
  "event": "beta_feedback.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "program": "Acme 2.0 Beta",
    "category": "bug",
    "severity": "high",
    "title": "Crash on export",
    "body": "The app closes when I export a large file.",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

severity peut être null.

beta_feedback.deleted

Un retour de bêta a été supprimé.

{
  "event": "beta_feedback.deleted",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "program": "Acme 2.0 Beta",
    "category": "bug",
    "severity": "high",
    "title": "Crash on export",
    "body": "The app closes when I export a large file.",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

waitlist_signup.created

Un visiteur a rejoint la liste d’attente.

{
  "event": "waitlist_signup.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "jamie@example.com",
    "status": "waiting",
    "position": 42,
    "referral_count": 0,
    "referral_code": "a1b2c3",
    "source": "portal",
    "created_at": "2026-07-15T12:00:00Z",
    "invited_at": null,
    "joined_at": null
  }
}

position vaut null pour les inscriptions invited et joined.

waitlist_signup.invited

Une inscription a été invitée depuis la liste d’attente.

{
  "event": "waitlist_signup.invited",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "jamie@example.com",
    "status": "invited",
    "position": null,
    "referral_count": 0,
    "referral_code": "a1b2c3",
    "source": "portal",
    "created_at": "2026-07-15T12:00:00Z",
    "invited_at": "2026-07-15T12:00:00Z",
    "joined_at": null
  }
}

waitlist_signup.joined

Une inscription invitée a accepté et rejoint.

{
  "event": "waitlist_signup.joined",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "jamie@example.com",
    "status": "joined",
    "position": null,
    "referral_count": 0,
    "referral_code": "a1b2c3",
    "source": "portal",
    "created_at": "2026-07-15T12:00:00Z",
    "invited_at": "2026-07-15T12:00:00Z",
    "joined_at": "2026-07-15T12:05:00Z"
  }
}

csat_survey.completed

Une enquête de satisfaction CSAT a été terminée avec une évaluation.

{
  "event": "csat_survey.completed",
  "data": {
    "thread_id": "550e8400-e29b-41d4-a716-446655440000",
    "rating": 5,
    "comment": "Support was fast and friendly.",
    "created_at": "2026-07-15T12:00:00Z"
  }
}

rating est un entier compris entre 1 et 5 ; comment peut être null.

Vérification des signatures

Chaque livraison inclut un header X-SupDesk-Signature :

X-SupDesk-Signature: sha256=a1b2c3d4e5f6...

La valeur après sha256= est le HMAC-SHA256 encodé en hexadécimal du corps brut de la requête, calculé à l’aide du secret de signature de votre webhook.

Étapes de vérification

  1. Lisez le corps brut de la requête (ne parsez pas JSON en premier)
  2. Calculez HMAC-SHA256(secret_de_signature, corps_brut)
  3. Comparez le digest hexadécimal avec la valeur dans le header de signature
  4. Utilisez une comparaison à temps constant pour prévenir les attaques temporelles

Exemple Node.js

import { createHmac, timingSafeEqual } from "crypto";
 
function verifySupDeskWebhook(secret, rawBody, signatureHeader) {
  const expected = createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const received = signatureHeader.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}
 
// Express example
app.post("/webhooks/supdesk", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-supdesk-signature"];
  if (!verifySupDeskWebhook(SECRET, req.body, sig)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  const event = JSON.parse(req.body);
  // Process event...
  res.status(200).json({ ok: true });
});

Exemple Python

import hmac
import hashlib
from flask import Flask, request, jsonify
 
app = Flask(__name__)
WEBHOOK_SECRET = "your-signing-secret"
 
def verify_signature(secret: str, body: bytes, header: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    received = header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)
 
@app.route("/webhooks/supdesk", methods=["POST"])
def handle_webhook():
    sig = request.headers.get("X-SupDesk-Signature", "")
    if not verify_signature(WEBHOOK_SECRET, request.data, sig):
        return jsonify(error="Invalid signature"), 401
    event = request.get_json()
    # Process event...
    return jsonify(ok=True), 200

Exemple Ruby

require "openssl"
require "sinatra"
require "json"
 
WEBHOOK_SECRET = "your-signing-secret"
 
def verify_signature(secret, body, header)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  received = header.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, received)
end
 
post "/webhooks/supdesk" do
  body = request.body.read
  sig = request.env["HTTP_X_SUPDESK_SIGNATURE"] || ""
  unless verify_signature(WEBHOOK_SECRET, body, sig)
    halt 401, { error: "Invalid signature" }.to_json
  end
  event = JSON.parse(body)
  # Process event...
  status 200
  { ok: true }.to_json
end

Nouvelles tentatives

Lorsqu’une livraison de webhook échoue, SupDesk effectue de nouvelles tentatives avec backoff exponentiel :

TentativeDélai
1Immédiat
21 seconde
32 secondes

Conditions de nouvelle tentative : réponses 5xx, erreurs réseau, timeouts (10 secondes).

Pas de nouvelle tentative : réponses 4xx (les erreurs client indiquent un problème de configuration).

Répondre aux webhooks

  • Retournez un code de statut 2xx pour accuser réception
  • Répondez dans les 10 secondes pour éviter les nouvelles tentatives de timeout
  • Traitez l’événement de manière asynchrone si votre logique prend plus de temps
  • Retournez la même réponse pour les livraisons en double (idempotence)
Last updated on
Centre d'aideErreurs