Skip to Content
Riferimento APIWebhook

Webhook (Ricezione)

Quando si verificano eventi nel tuo progetto SupDesk, i webhook in uscita inoltrano richieste HTTP POST ai tuoi endpoint configurati. Questa pagina documenta il formato del payload, il meccanismo di firma e il comportamento dei tentativi ripetuti in modo che tu possa creare ricevitori webhook affidabili.

Formato del payload

Ogni consegna di webhook usa un involucro standard:

{
  "event": "post.created",
  "timestamp": "2026-07-15T12:00:00.000Z",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": { ... }
}
CampoTipoDescrizione
eventstringL’evento che ha innescato la consegna
timestampstringTimestamp ISO 8601 della produzione dell’evento
project_idstringUUID del progetto in cui si è verificato l’evento
dataobjectPayload specifico per l’evento (vedi sotto)

Eventi

post.created

È stato inviato un nuovo post di feedback.

{
  "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 di feedback è stato modificato.

{
  "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 di feedback è stato eliminato.

{
  "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

Lo stato di un post è stato modificato.

{
  "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

È stato aggiunto un nuovo commento a 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 commento è stato modificato.

{
  "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 commento è stato eliminato.

{
  "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

È stato inviato un nuovo messaggio privato.

{
  "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 messaggio privato è stato modificato.

{
  "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 messaggio privato è stato eliminato.

{
  "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 tester beta ha inviato feedback su un programma beta.

{
  "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 può essere null.

beta_feedback.deleted

Un feedback della beta è stato eliminato.

{
  "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 visitatore si è unito alla lista d’attesa.

{
  "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 è null per le iscrizioni invited e joined.

waitlist_signup.invited

Un’iscrizione è stata invitata dalla lista d’attesa.

{
  "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

Un’iscrizione invitata ha accettato e si è unita.

{
  "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

Un sondaggio di soddisfazione CSAT è stato completato con una valutazione.

{
  "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 è un numero intero compreso tra 1 e 5; comment può essere null.

Verifica delle firme

Ogni consegna include un header X-SupDesk-Signature:

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

Il valore dopo sha256= è l’HMAC-SHA256 codificato in esadecimale del corpo grezzo della richiesta, calcolato usando il segreto di firma del tuo webhook.

Passaggi di verifica

  1. Leggi il corpo grezzo della richiesta (non analizzare prima il JSON)
  2. Calcola HMAC-SHA256(segreto_di_firma, corpo_grezzo)
  3. Confronta il digest esadecimale con il valore nell’header della firma
  4. Usa un confronto a tempo costante per prevenire attacchi di timing

Esempio 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 });
});

Esempio 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

Esempio 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

Tentativi ripetuti

Quando una consegna di webhook fallisce, SupDesk riprova con backoff esponenziale:

TentativoRitardo
1Immediato
21 secondo
32 secondi

Condizioni di ripetizione: risposte 5xx, errori di rete, timeout (10 secondi).

Non ripetuto: risposte 4xx (gli errori client indicano un problema di configurazione).

Rispondere ai webhook

  • Restituisci un codice di stato 2xx per confermare la ricezione
  • Rispondi entro 10 secondi per evitare ripetizioni per timeout
  • Elabora l’evento in modo asincrono se la tua logica richiede più tempo
  • Restituisci la stessa risposta per consegne duplicate (idempotenza)
Last updated on
Centro assistenzaErrori