Vai al contenuto
Logo Aurabase
aurabase

Webhook in uscita e firme HMAC

Ricevi eventi in tempo reale dal tuo progetto Aurabase sui tuoi server in modo sicuro utilizzando le firme crittografiche HMAC-SHA256.

Guida pratica8 min lettoLivello intermedioRevisionato il 19 ago 2026

Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.

Architettura dei webhook#

Aurabase webhook in uscita trasmettono eventi di sistema agli URL di callback (ad esempio registrazione di un nuovo utente, pagamento riuscito, aggiornamento di righe di tabella).

Garanzia di consegna almeno una volta

Ogni webhook inviato contiene un identificatore di evento univoco event_id che ti consente di implementare l'elaborazione idempotente sui tuoi server.

Struttura dell'intestazione X-Aurabase-Signature#

Ogni richiesta HTTP POST emessa da Aurabase include la seguente intestazione di sicurezza:

http-headerstext
POST /webhook HTTP/1.1
Host: api.votre-domaine.com
Content-Type: application/json
X-Aurabase-Event-Id: evt_01J8Y6Q9K3M7Z...
X-Aurabase-Signature: t=1724060000,v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Verifica la firma HMAC-SHA256#

verify-webhook.tstypescript
import crypto from 'node:crypto'
export function verifyAurabaseWebhook(
  rawBody: string, signatureHeader: string, secret: string
): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('=')),
  )
  const { t: timestamp, v1: signature } = parts

  // 1. Protezione contro gli attacchi di replay (5 minuti max)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return false
  }

  // 2. Calcolo di HMAC-SHA256 su timestamp.rawBody
  const expected = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex')

  // 3. Confronto sicuro in tempo costante
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected)
  )
}

Gestione dei guasti e coda dei messaggi non recapitati#

Se il tuo server risponde con un codice di errore HTTP (4xx, 5xx) o riscontra un timeout (limite di tempo di 10 secondi), Aurabase ritenta automaticamente l'invio in base a un backoff esponenziale :

  • Tentativo 1: immediato
  • Tentativo 2: dopo 15 secondi
  • Tentativo 3: dopo 1 minuto
  • Tentativo 4: dopo 5 minuti
  • Tentativo 5: dopo 30 minuti

Dopo 5 errori consecutivi, l'evento viene inserito nella Dead-Letter Queue (DLQ) dello Studio per l'ispezione e la riproduzione manuale.

Per andare oltre#