Webhook

RolChat consegna gli eventi ai tuoi sistemi come richieste HTTP POST firmate. Questa pagina descrive i webhook dei plugin; i webhook inviati da una regola di Automazione differiscono per nuovi tentativi, tempo di attesa e rotazione del segreto, vedi Webhook di automazione. Le stesse regole valgono nella direzione opposta, quando il tuo sistema, un plugin o un provider inviano dati a RolChat. Verifica ogni consegna nell’ordine indicato sotto prima di agire.

Com’è fatta una consegna

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: RolChat-Webhook/1.0
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=a1b2c3…
X-RolChat-Nonce: nonce_01HKQN9…
X-RolChat-Event-Id: evt_01HKQN9…

{ "id": "evt_01HKQN9…", "type": "conversation.created", "occurred_at": "…", "data": { … } }

Intestazione	Significato
`X-RolChat-Timestamp`	Secondi Unix al momento dell’invio. Fa parte del messaggio firmato.
`X-RolChat-Signature`	`sha256=<hex>`. Il prefisso indica l’algoritmo, così in futuro potrà cambiare.
`X-RolChat-Nonce`	Un ULID univoco per questa richiesta HTTP. Un nuovo tentativo riceve un nuovo nonce.
`X-RolChat-Event-Id`	L’ID proprio dell’evento. Stabile tra i tentativi; usalo per deduplicare.

Le consegne in uscita vanno solo a endpoint HTTPS. Un URL HTTP viene rifiutato al momento della creazione dell’iscrizione.

La firma

Il messaggio firmato è composto dal timestamp, un punto letterale e il corpo grezzo della richiesta, byte per byte:

canonical = "<timestamp>.<body>"
signature = hex( HMAC-SHA256( secret, canonical ) )

Firma i byte che hai ricevuto, non una copia riserializzata del JSON analizzato. Modifiche agli spazi o all’ordine delle chiavi invalidano la firma. SHA-256 è l’unico algoritmo accettato.

Le richieste inviate dall’azione HTTP del modulo Automazione sono firmate con due intestazioni. X-RolChat-Signature è sha256= seguito dall’HMAC-SHA256 del solo corpo. X-RolChat-Signature-V2 è l’HMAC-SHA256 di <timestamp>.<body>, lo schema descritto sopra, con X-RolChat-Timestamp come timestamp. Verifica l’intestazione V2: quella calcolata sul solo corpo non protegge da una richiesta riproposta. Queste richieste non hanno X-RolChat-Nonce né X-RolChat-Event-Id; tutti i tentativi di una stessa consegna portano lo stesso X-RolChat-Delivery-Id e il proprio numero in X-RolChat-Attempt, quindi salta il controllo sul nonce e deduplica per X-RolChat-Delivery-Id. Gli esempi di verifica leggono X-RolChat-Signature: per le richieste di automazione leggi invece X-RolChat-Signature-V2.

Verificare una consegna

Esegui questi cinque controlli nell’ordine. Esempi in Python, Node.js, Go, Ruby e PHP si trovano nella pagina esempi di verifica.

Validità temporale. Rifiuta se |now − X-RolChat-Timestamp| > 300 secondi (400). Cinque minuti tollerano lo sfasamento degli orologi e rendono inutile una richiesta intercettata dopo quel tempo. Tieni il tuo server sincronizzato con NTP.
Firma. Calcola il valore atteso e confrontalo con un confronto a tempo costante (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). In caso di discordanza rifiuta con 401. Un semplice confronto tra stringhe rivela informazioni tramite i tempi e non è accettabile.
Nonce. Salva X-RolChat-Nonce con un TTL di 10 minuti usando un set-if-absent atomico (SET NX EX 600). Se esiste già, rifiuta con 409: la richiesta è un replay. Se l’archivio dei nonce non è disponibile, fallisci in modo chiuso con 503 così RolChat riprova; non ricadere mai su “accetta”.
Analizza il corpo solo a questo punto.
Deduplica per ID evento. I nuovi tentativi hanno un nuovo nonce ma lo stesso X-RolChat-Event-Id. Se hai elaborato quell’ID negli ultimi sette giorni, rispondi 200 senza elaborarlo di nuovo.

Rispondi 2xx non appena la consegna è stata accettata in sicurezza; svolgi il lavoro in modo asincrono. RolChat attende una risposta per 15 secondi.

Segreti

Un segreto webhook è composto da 64 byte casuali codificati in base64url (circa 86 caratteri). Viene generato quando si crea l’iscrizione o il plugin e mostrato una sola volta.
Conservalo nel tuo vault o nelle variabili d’ambiente; RolChat conserva solo una copia cifrata.
Si consiglia la rotazione dopo 90 giorni; il prodotto mostra un promemoria ma non disattiva mai un’iscrizione per mancata rotazione.
La rotazione usa una finestra di sovrapposizione: dopo POST /api/v1/plugins/{id}/webhook-secret/rotate sia il vecchio sia il nuovo segreto sono validi per sette giorni, le nuove consegne vengono firmate con quello nuovo e il vecchio viene eliminato al termine della finestra. Nulla si rompe nel momento in cui esegui la rotazione.
Se un segreto trapela, POST /api/v1/plugins/{id}/webhook-secret/revoke lo invalida immediatamente, ne emette uno nuovo, invia un’email agli amministratori dell’account e scrive una voce di audit.

Nuovi tentativi e dead letter

Una risposta diversa da 2xx o un errore di rete pianifica un nuovo tentativo:

Tentativo	Ritardo rispetto al precedente
1	immediato
2	15 secondi
3	1 minuto
4	5 minuti
5	30 minuti
6	2 ore
7	8 ore
8	24 ore

408, 429, 5xx e gli errori di rete vengono ritentati. 400, 401, 403, 404 e 410 no: la consegna va direttamente nella dead-letter queue, perché ripetere una firma rifiutata o un endpoint inesistente non può servire. Dopo otto tentativi falliti anche la consegna finisce tra le dead letter.

Le dead letter vengono conservate per 30 giorni e sono visibili in Impostazioni → Plugin → {plugin} → Log dei webhook → DLQ, dove un amministratore può riprodurne una (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limiti

Corpo in uscita: 1 MB per impostazione predefinita (configurabile per plugin). Corpo in entrata verso RolChat: 5 MB. Oltre si ottiene 413.
Un plugin può dichiarare allowed_source_ips; RolChat applica quella allowlist prima della verifica.
Come ulteriore controllo di coerenza puoi verificare lo user agent RolChat-Webhook/1.0. Non è una misura di sicurezza.

Webhook in entrata verso RolChat

I provider inviano dati a RolChat su /api/v1/webhooks/{category}/{adapter} usando i propri schemi di firma (Twilio, Telnyx, Bandwidth, Meta per WhatsApp, Stripe). Ogni adattatore verifica la firma del proprio provider, normalizza il payload e lo ripubblica sul bus eventi interno con una firma RolChat. Il tuo sistema può inviare dati a RolChat con le stesse intestazioni X-RolChat-* descritte sopra, firmate con il segreto del plugin a cui appartiene l’endpoint.

Webhook di automazione

L’azione Invia richiesta HTTP del modulo Automazione ha regole di consegna proprie:

Un segreto per account. Mostralo o ruotalo nella schermata Automazione (Proprietario e Amministratore). La rotazione ha effetto subito: non c’è finestra di sovrapposizione, il vecchio segreto smette di verificarsi immediatamente, quindi aggiorna prima il tuo ricevitore o accetta una breve interruzione.
Tempo di attesa: RolChat attende 10 secondi una risposta.
Nuovi tentativi: fino a 6 tentativi in totale. La pausa prima del tentativo 2 è di 30 secondi, poi circa 2 minuti, 8 minuti, 32 minuti e 2 ore 8 minuti, ciascuna con una variazione fino al 20 %. Una singola pausa non supera mai le 6 ore.
Cosa viene ritentato: errori di rete, timeout, 5xx, 408, 425 e 429. Le altre risposte 4xx, un indirizzo bloccato o un corpo troppo grande non vengono ritentati: la consegna va direttamente nella coda dei messaggi falliti, come dopo l’ultimo tentativo non riuscito.
Intestazioni: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Testare il tuo ricevitore

POST /api/v1/webhooks/test-signature invia un evento sintetico firmato all’endpoint del plugin chiamante, così puoi verificare la tua implementazione dall’inizio alla fine prima che arrivi il traffico reale.

Errori comuni

Verificare sul JSON analizzato e ricodificato invece che sui byte grezzi.
Usare == per confrontare le firme.
Deduplicare per nonce (ogni nuovo tentativo ne ha uno nuovo) invece che per ID evento.
Un orologio sfasato di oltre cinque minuti.
Svolgere lavoro lento prima di rispondere, andare in timeout dopo 15 secondi e ricevere di nuovo lo stesso evento.