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.
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).
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:
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#
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.