Saltar para o conteúdo principal
Deel

Deel webhooks com o Odoo: assinatura, eventos, novas tentativas e o que faz o conector

A Deel pode avisar por webhook quando muda um pagamento, um recibo de vencimento ou um contrato, e assina cada aviso com HMAC-SHA256. O conector da Deel da FlexigoTech usa esses avisos como uma campainha: verifica a assinatura, aponta o que tocou e volta a ler o dado pela API. E revê tudo a cada 30 minutos: na lista de eventos da Deel de 18-11-2026, por exemplo, não há um de fatura emitida.

FlexigoTech · Responsável: Víctor Gómez · Atualizado em 18 de novembro de 2026

O essencial

Módulo
Deel
Versões
Odoo 17, 18, 19 e 20
Verificado
no código do conector, versão 20.0 · nas fontes indicadas no fim
Leitura
7 min

Como a Deel avisa

Quando acontece algo na conta, a Deel faz um POST para o endereço do webhook com um JSON que traz o tipo de evento em data.meta.event_type, a organização, o recurso que mudou e a hora. Cada entrega leva três cabeçalhos: x-deel-signature, com a assinatura; x-deel-hmac-label, que diz que chave de assinatura foi usada; e x-deel-webhook-version. Os webhooks criam-se pela API, com POST /webhooks, ou no separador Webhooks do Developer Center, e para isso é preciso ser Org Admin ou IT Developer Admin na Deel. Um webhook criado no sandbox só recebe eventos do sandbox.

Como se verifica a assinatura

A Deel calcula um HMAC-SHA256 da palavra POST seguida do corpo tal como chega, com a chave de assinatura do webhook, e pede que se verifique antes de processar seja o que for. Essa chave (signing_key) é devolvida pela Deel ao criar o webhook, e é a própria Deel que a gera se não lhe for dada uma. Os seus exemplos de código produzem a assinatura em hexadecimal.

O controlador do conector faz o mesmo cálculo com a chave guardada na ligação, compara-o com x-deel-signature em tempo constante e responde assim:

O que chega ao OdooResposta
Assinatura válida200, com o evento apontado na fila
Sem assinatura ou com uma assinatura errada401
Um token de endereço desconhecido ou um webhook desativado no Odoo404
Um corpo com mais de 1 MB413

Ao contrário do token da API, que a FlexigoTech Cloud guarda, a chave de assinatura fica no Odoo, na ligação, num campo reservado aos administradores. Os testes do módulo verificam a assinatura com o cálculo do exemplo em Python da Deel, e a criação e a remoção do webhook foram testadas contra a organização de demonstração da Deel.

Que eventos existem

A página de eventos da Deel fala de mais de 100 («100+ Events») e, para a lista completa, remete para GET /webhooks/events/types, que pede a permissão webhooks:read. No índice da sua referência da API, copiado a 18-11-2026, há 56 eventos com página própria. Nessa lista não há nenhum evento de fatura emitida nem de relatório bruto-líquido: de faturas só estão os ajustes (Invoice Adjustment Created, Pending For Approval e Reviewed); de salários, os de recibos disponíveis do Global Payroll e de EOR e o de um documento de recibo apagado; e de pagamentos, o extrato iniciado e o marcado como pago.

O conector subscreve 12 desses eventos, e cada um só lhe diz que parte da sincronização deve correr:

Eventos da DeelO que o conector volta a ler
payment.statement.initiated, payment.statement.mark-paidOs pagamentos
invoice-adjustment.created, invoice-adjustment.reviewed, eor.payslips.availableAs faturas
gp.payslips.availableOs salários do Global Payroll
contract.created, contract.status.updated, contract.terminated, worker.v2.created, worker.v2.updated, worker.v2.deletedAs pessoas e os contratos

Um evento que o conector não conhece é apontado e dado como feito sem correr nada.

Novas tentativas e desativação, segundo a Deel

Se o endereço não responder com um 2xx, ou demorar mais de 30 segundos, a Deel conta uma falha e volta a tentar com esperas de 1, 2, 4, 8, 16 e 32 minutos, depois de 1, 2 e 4 horas, e uma décima tentativa ao fim de 16 horas. Com 10 falhas seguidas desativa a subscrição, que depois tem de ser reativada à mão, pela API ou no Developer Center. A Deel pede uma resposta 200 em menos de 30 segundos, de preferência em menos de 5, e avisa que o mesmo evento pode chegar mais de uma vez.

O conector responde assim que aponta o evento; a sincronização vem depois, na fila. No Odoo, Webhook Ativo só se desmarca com Remover webhook ou com Desconectar, e o conector não pergunta à Deel em que estado está o webhook. Se a Deel o desativar após 10 falhas, por exemplo porque o Odoo esteve em baixo, o Odoo vai continuar a vê-lo ativo: reativa-se no Developer Center da Deel, ou remove-se e volta a registar-se a partir do Odoo. Entretanto, a sincronização a cada 30 minutos continua a trazer o mesmo. Para saber o que aconteceu a cada entrega, cada webhook tem no Developer Center um separador Logs com o código que o seu Odoo devolveu; um 401 aí aponta para a assinatura.

O que faz o conector quando toca

A Deel chama diretamente o seu Odoo, num endereço https que leva um token aleatório de cada ligação, por isso a FlexigoTech Cloud não está no meio da entrega. Pela FlexigoTech Cloud passam a criação e a remoção do webhook e as leituras que vêm depois. Com a assinatura válida, o Odoo aponta na fila o tipo de evento, sem tomar o conteúdo como dado, e acorda a tarefa Deel: fila de webhooks, que além disso corre sozinha a cada hora. Essa tarefa vê que partes tocaram em cada ligação e corre cada uma uma só vez, mesmo que tenham chegado vários avisos, voltando a ler os dados da Deel pela API.

Ficha da ligação da Deel no Odoo com os botões Testar conexão, Sincronizar agora e Desconectar, o ambiente Produção e o texto da FlexigoTech Cloud, que refere os webhooks entre as chamadas à Deel
A ligação da Deel no Odoo, com o texto da FlexigoTech Cloud que refere os webhooks entre as chamadas à Deel (organização inventada, dados de demonstração).

Como se cria a partir do Odoo

No separador Webhooks da ligação, um administrador carrega em Registar webhook. O botão só aparece se a ligação já não estiver em Não conectado (o token já está guardado) e o webhook não estiver ativo, e é preciso ainda:

  • que o Odoo esteja em https, porque senão o conector para e lembra que «A sincronização agendada continua a funcionar sem webhooks.»;
  • que o token tenha webhooks:write, a permissão que a Deel pede para criar e para apagar um webhook; com um token só de leitura, a Deel responde 403 ou 401, segundo o seu guia de autenticação. Com um 403, o conector mostra o motivo que a Deel indica; com um 401, diz que a Deel recusou o token e pede para guardar um novo, mesmo que ao token só falte essa permissão.

O conector envia à Deel um nome que começa por Odoo, o endereço, os 12 eventos da tabela e a versão v2 da API, e guarda o identificador e a chave de assinatura que a Deel devolve. Se tudo correr bem, avisa que a Deel vai chamar o Odoo quando um pagamento, um recibo de vencimento ou um contrato mudar. Remover webhook apaga-o na Deel, e Desconectar também, se o serviço FlexigoTech Cloud estiver ativo.

Definições da FlexigoTech Cloud no Odoo com o cartão do conector da Deel em teste, com o seu preço e o texto que diz que mantém a ligação com a plataforma através da FlexigoTech Cloud
O conector da Deel nas definições da FlexigoTech Cloud, em teste (dados de demonstração).

Porque revê também a cada 30 minutos

A Deel recomenda não confiar só nos webhooks e fazer reconciliações de vez em quando. O conector fá-lo com a tarefa Deel: sincronizar contratos, faturas, pagamentos, folha de pagamento e centros de custo, que corre a cada 30 minutos, com ou sem webhooks. E há motivos do lado da Deel para não a tirar: na sua lista não há um evento de fatura emitida, por isso as faturas novas chegam com essa revisão; um webhook que a Deel desativa não avisa o Odoo; e um Odoo sem https não os pode receber. Com webhooks, um pagamento, um recibo de vencimento ou um contrato chegam assim que a Deel avisa; sem eles, na passagem seguinte.

O que foi testado

Contra a organização de demonstração da Deel (demo.deel.com), através da FlexigoTech Cloud, foram testados a ligação, as entidades legais, um contrato com a sua pessoa e o seu fornecedor, os webhooks e uma segunda passagem sem duplicados. Faturas, pagamentos e ciclos salariais foram testados com respostas construídas sobre a referência da API da Deel, porque essa organização ainda não tinha. O conector funciona no Odoo 17, 18, 19 e 20, num servidor próprio ou no Odoo.sh, e não no Odoo Online. O token e as suas permissões estão no guia do Deel API token, e o que entra como fatura de fornecedor, em Deel invoice. O conector está explicado por inteiro na sua página e publicado na Odoo Apps.

Continue a ler

Deel API token para o Odoo: criá-lo, dar-lhe permissões e colá-loComo se cria o token de organização da Deel, que permissão a Deel pede para cada chamada do conector, onde se cola no Odoo e para onde vai ao guardar.Deel invoice no Odoo: da fatura da Deel à fatura de fornecedorO que traz uma Deel invoice de prestadores, EOR ou comissões da Deel e como entra no Odoo como fatura de fornecedor, com IVA, PDF e centros de custo.
Verificado no código do conector (versão 20.0) e nas fontes indicadas

Fontes