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 Odoo | Resposta |
|---|---|
| Assinatura válida | 200, com o evento apontado na fila |
| Sem assinatura ou com uma assinatura errada | 401 |
| Um token de endereço desconhecido ou um webhook desativado no Odoo | 404 |
| Um corpo com mais de 1 MB | 413 |
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 Deel | O que o conector volta a ler |
|---|---|
payment.statement.initiated, payment.statement.mark-paid | Os pagamentos |
invoice-adjustment.created, invoice-adjustment.reviewed, eor.payslips.available | As faturas |
gp.payslips.available | Os salários do Global Payroll |
contract.created, contract.status.updated, contract.terminated, worker.v2.created, worker.v2.updated, worker.v2.deleted | As 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.

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.

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
Verificado no código do conector (versão 20.0) e nas fontes indicadas
Fontes
- developer.deel.com/api/webhooks/introduction
- developer.deel.com/api/webhooks/quickstart
- help.letsdeel.com/hc/en-gb/articles/10660690287761-How-To-Create-And-Manage-Webhooks-Notif
- developer.deel.com/api/webhooks/no-code
- developer.deel.com/api/endpoints/webhooks/create-webhook
- developer.deel.com/api/endpoints/webhooks/delete-webhook
- developer.deel.com/api/webhooks/events
- developer.deel.com/api/stable/llms.txt
- developer.deel.com/api/endpoints/webhooks/get-webhook-events
- Código do módulo: flexigo_deel_connector 20.0 (18442307): models/deel_account.py
- Código do módulo: flexigo_deel_connector 20.0 (18442307): controllers/main.py
- Código do módulo: flexigo_deel_connector 20.0 (18442307): data/deel_cron.xml
- Código do módulo: flexigo_deel_connector 20.0 (18442307): static/description/index.html
- Código do módulo: flexigo_deel_connector 20.0 (18442307): tests/test_webhook.py
- developer.deel.com/api/authentication
- apps.odoo.com/apps/modules/20.0/flexigo_deel_connector
- Código do módulo: flexigo_deel_connector 20.0 (18442307): views/deel_account_views.xml
