Webhook

I webhook in uscita ti permettono di ricevere notifiche HTTP POST in tempo reale quando si verificano eventi nel tuo progetto. Pro

Panoramica

I webhook consegnano un payload JSON a qualsiasi endpoint HTTPS che configuri quando si verifica un evento specifico nel tuo progetto. Ogni webhook può iscriversi a uno o più dei seguenti eventi:

I webhook sono configurati per singolo progetto. Ogni progetto ha il proprio insieme di endpoint webhook con configurazioni e segreti di firma indipendenti.

Configurare un webhook

1. Vai alla pagina Integrazioni del tuo progetto
2. Scorri fino alla sezione Webhook in uscita
3. Clicca su Aggiungi webhook
4. Inserisci l’URL del tuo endpoint (deve essere HTTPS in produzione)
5. Seleziona a quali eventi iscriverti
6. Clicca su Salva

Dopo il salvataggio, viene mostrato una volta un segreto di firma. Copianalo immediatamente — non può essere recuperato in seguito. Puoi rigenerarlo in qualsiasi momento dal menu azioni del webhook.

Verificare le firme dei webhook

Ogni consegna di webhook include un header X-SupDesk-Signature contenente una firma HMAC-SHA256 del corpo della richiesta. Per verificare un webhook:

1. Calcola HMAC-SHA256(tuo_segredo_di_firma, corpo_raw_della_richiesta)
2. Confronta il risultato con il valore esadecimale nell’header X-SupDesk-Signature (dopo il prefisso sha256=)
3. Usa un confronto a tempo costante per prevenire attacchi di timing

Node.js

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

Python

import hmac
import hashlib
 
def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    sig = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, sig)

Ruby

require "openssl"
 
def verify_webhook(secret, body, signature)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  sig = signature.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, sig)
end

Testare un webhook

Clicca sul pulsante Test accanto a un webhook per inviare un payload di esempio al suo endpoint. Il payload di test ha "event": "test" e un campo data.message. Usa uno strumento come webhook.site  per ispezionare la richiesta consegnata.

Registro delle consegne

Il registro delle consegne mostra gli ultimi 50 tentativi di consegna per ogni webhook, inclusi:

• Evento — quale evento è stato consegnato
• Stato — success o failed
• Codice di risposta — codice di stato HTTP dell’endpoint
• Tentativi — numero di tentativi di consegna (inclusi i tentativi ripetuti)
• Ora — quando è stato tentato la consegna

Comportamento dei tentativi ripetuti

Quando una consegna di webhook fallisce (risposta 5xx o timeout di rete), SupDesk riprova fino a 3 volte con backoff esponenziale:

Gli errori client (4xx) non vengono riprovati — indicano un problema permanente con la configurazione dell’endpoint.

Requisiti del piano

I webhook in uscita sono disponibili sui piani Pro e Team.