Vai al contenuto principale
Deel

Deel webhooks con Odoo: firma, eventi, nuovi tentativi e cosa fa il connettore

Deel può avvisare via webhook quando cambia un pagamento, una busta paga o un contratto, e firma ogni avviso con HMAC-SHA256. Il connettore Deel di FlexigoTech usa questi avvisi come un campanello: controlla la firma, annota cosa ha suonato e rilegge il dato tramite l'API. In più ricontrolla tutto ogni 30 minuti: nella lista degli eventi di Deel del 18-11-2026, per esempio, non ce n'è uno per una fattura emessa.

FlexigoTech · Responsabile: Víctor Gómez · Aggiornato il 18 novembre 2026

In breve

Modulo
Deel
Versioni
Odoo 17, 18, 19 e 20
Verificato
nel codice del connettore, versione 20.0 · nelle fonti collegate in fondo
Lettura
6 min

Come avvisa Deel

Quando succede qualcosa nell'account, Deel fa un POST all'indirizzo del webhook con un JSON che porta il tipo di evento in data.meta.event_type, l'organizzazione, la risorsa cambiata e l'ora. Ogni consegna ha tre intestazioni: x-deel-signature, con la firma; x-deel-hmac-label, che dice quale chiave di firma è stata usata; e x-deel-webhook-version. I webhook si creano tramite l'API, con POST /webhooks, o nella scheda Webhooks del Developer Center, e per farlo bisogna essere Org Admin o IT Developer Admin in Deel. Un webhook creato nel sandbox riceve solo eventi del sandbox.

Come si controlla la firma

Deel calcola un HMAC-SHA256 della parola POST seguita dal corpo così come arriva, con la chiave di firma del webhook, e chiede di controllarlo prima di elaborare qualsiasi cosa. Quella chiave (signing_key) la restituisce Deel quando si crea il webhook, e la genera lui se non gliene viene data una. I suoi esempi di codice producono la firma in esadecimale.

Il controller del connettore fa lo stesso calcolo con la chiave salvata nella connessione, lo confronta con x-deel-signature in tempo costante e risponde così:

Cosa arriva a OdooRisposta
Firma valida200, con l'evento annotato in coda
Nessuna firma o una firma sbagliata401
Un token di indirizzo sconosciuto o un webhook disattivato in Odoo404
Un corpo di oltre 1 MB413

A differenza del token dell'API, che conserva FlexigoTech Cloud, la chiave di firma resta in Odoo, nella connessione, in un campo riservato agli amministratori. I test del modulo controllano la firma con il calcolo dell'esempio Python di Deel, e la creazione e la cancellazione del webhook sono state provate contro l'organizzazione dimostrativa di Deel.

Quali eventi ci sono

La pagina degli eventi di Deel parla di oltre 100 («100+ Events») e, per la lista completa, rimanda a GET /webhooks/events/types, che chiede il permesso webhooks:read. Nell'indice della sua documentazione di riferimento dell'API, copiato il 18-11-2026, ci sono 56 eventi con una pagina propria. In questa lista non c'è nessun evento di fattura emessa né di report lordo-netto: per le fatture ci sono solo gli adeguamenti (Invoice Adjustment Created, Pending For Approval e Reviewed); per le paghe, quelli delle buste paga disponibili di Global Payroll e di EOR e quello di un documento di paga cancellato; e per i pagamenti, l'estratto avviato e quello segnato come pagato.

Il connettore si iscrive a 12 di questi eventi, e ognuno gli dice solo quale parte della sincronizzazione eseguire:

Eventi di DeelCosa rilegge il connettore
payment.statement.initiated, payment.statement.mark-paidI pagamenti
invoice-adjustment.created, invoice-adjustment.reviewed, eor.payslips.availableLe fatture
gp.payslips.availableLe paghe di Global Payroll
contract.created, contract.status.updated, contract.terminated, worker.v2.created, worker.v2.updated, worker.v2.deletedLe persone e i contratti

Un evento che il connettore non conosce viene annotato e segnato come fatto senza eseguire nulla.

Nuovi tentativi e disattivazione, secondo Deel

Se l'indirizzo non risponde con un 2xx, o ci mette più di 30 secondi, Deel lo conta come errore e riprova con attese di 1, 2, 4, 8, 16 e 32 minuti, poi di 1, 2 e 4 ore, e un decimo tentativo dopo 16 ore. Dopo 10 errori di fila disattiva l'iscrizione, che poi va riattivata a mano, tramite l'API o nel Developer Center. Deel chiede di rispondere 200 entro 30 secondi, meglio entro 5, e avvisa che uno stesso evento può arrivare più di una volta.

Il connettore risponde appena ha annotato l'evento; la sincronizzazione arriva dopo, in coda. In Odoo, Webhook Attivo si toglie solo con Rimuovi Webhook o con Disconnetti, e il connettore non chiede a Deel in che stato è il webhook. Se Deel lo disattiva dopo 10 errori, per esempio perché Odoo era fermo, Odoo continuerà a vederlo attivo: si riattiva nel Developer Center di Deel, oppure si rimuove e si registra di nuovo da Odoo. Nel frattempo la sincronizzazione ogni 30 minuti continua a portare gli stessi dati. Per sapere cosa è successo a ogni consegna, ogni webhook ha nel Developer Center una scheda Logs con il codice restituito dal tuo Odoo; un 401 lì indica un problema di firma.

Cosa fa il connettore quando suona

Deel chiama direttamente il tuo Odoo, a un indirizzo https che contiene un token casuale per ogni connessione, quindi FlexigoTech Cloud non sta in mezzo alla consegna. Da FlexigoTech Cloud passano la creazione e la rimozione del webhook e le letture che vengono dopo. Con una firma valida, Odoo annota in coda il tipo di evento, senza prendere il contenuto come dato, e sveglia l'attività Deel: coda webhook, che in più gira da sola ogni ora. Quell'attività guarda quali parti hanno suonato in ogni connessione ed esegue ciascuna una sola volta, anche se sono arrivati più avvisi, rileggendo i dati da Deel tramite l'API.

Scheda della connessione Deel in Odoo con i pulsanti Prova connessione, Sincronizza Ora e Disconnetti, l'ambiente Produzione e il testo di FlexigoTech Cloud, che nomina i webhook tra le chiamate a Deel
La connessione Deel in Odoo, con il testo di FlexigoTech Cloud che nomina i webhook tra le chiamate a Deel (organizzazione inventata, dati dimostrativi).

Come si registra da Odoo

Nella scheda Webhooks della connessione, un amministratore preme Registra Webhook. Il pulsante compare solo se la connessione non è più in Non connesso (il token è già salvato) e il webhook non è attivo, e in più serve:

  • che Odoo sia in https, perché altrimenti il connettore si ferma e ricorda che la sincronizzazione pianificata continua a funzionare senza webhook;
  • che il token abbia webhooks:write, il permesso che Deel chiede per creare e per cancellare un webhook; con un token di sola lettura, Deel risponde 403 o 401, secondo la sua guida all'autenticazione. Con un 403, il connettore mostra il motivo che dà Deel; con un 401, dice che Deel ha rifiutato il token e chiede di salvarne uno nuovo, anche se al token manca solo quel permesso.

Il connettore manda a Deel un nome che comincia con Odoo, l'indirizzo, i 12 eventi della tabella e la versione v2 dell'API, e salva l'identificativo e la chiave di firma che Deel restituisce. Se va tutto bene, avvisa: «Deel chiamerà Odoo quando un pagamento, una busta paga o un contratto cambia.» Rimuovi Webhook lo cancella in Deel, e anche Disconnetti, se il servizio FlexigoTech Cloud è attivo.

Impostazioni di FlexigoTech Cloud in Odoo con la scheda del connettore Deel in prova, con il suo prezzo e il testo che dice che mantiene attiva la connessione con la piattaforma tramite FlexigoTech Cloud
Il connettore Deel nelle impostazioni di FlexigoTech Cloud, in prova (dati dimostrativi).

Perché ricontrolla anche ogni 30 minuti

Deel consiglia di non affidarsi solo ai webhook e di riallineare ogni tanto. Il connettore lo fa con l'attività Deel: sincronizza contratti, fatture, pagamenti, paga e centri di costo, che gira ogni 30 minuti, con i webhook o senza. E ci sono motivi, dal lato di Deel, per non toglierla: nella sua lista non c'è un evento di fattura emessa, quindi le fatture nuove arrivano con questo ricontrollo; un webhook che Deel disattiva non avvisa Odoo; e un Odoo senza https non può riceverli. Con i webhook, un pagamento, una busta paga o un contratto arrivano appena Deel avvisa; senza, al passaggio successivo.

Cosa è stato provato

Contro l'organizzazione dimostrativa di Deel (demo.deel.com), tramite FlexigoTech Cloud, sono stati provati la connessione, le entità legali, un contratto con la sua persona e il suo fornitore, i webhook e un secondo passaggio senza duplicati. Fatture, pagamenti e cicli di paga sono stati provati con risposte costruite sul riferimento dell'API di Deel, perché quell'organizzazione non ne aveva ancora. Il connettore funziona su Odoo 17, 18, 19 e 20, sul tuo server o su Odoo.sh, e non su Odoo Online. Il token e i suoi permessi sono nella guida al Deel API token, e quello che entra come fattura fornitore, in Deel invoice. Il connettore è spiegato per intero nella sua pagina ed è pubblicato su Odoo Apps.

Continua a leggere

Deel API token per Odoo: crearlo, dargli i permessi e incollarloCome si crea il token di organizzazione di Deel, quale permesso chiede Deel per ogni chiamata del connettore, dove si incolla in Odoo e dove finisce.Deel invoice in Odoo: dalla fattura di Deel alla fattura fornitoreCosa contiene una Deel invoice di collaboratori, EOR o commissioni Deel e come arriva in Odoo come fattura fornitore, con IVA, PDF e centri di costo.
Verificato nel codice del connettore (versione 20.0) e nelle fonti collegate

Fonti