Cómo avisa Deel
Cuando pasa algo en la cuenta, Deel hace un POST a la dirección del webhook con un JSON que trae el tipo de evento en data.meta.event_type, la organización, el recurso que cambió y la hora. Cada entrega lleva tres cabeceras: x-deel-signature, con la firma; x-deel-hmac-label, que dice qué clave de firma se usó; y x-deel-webhook-version. Los webhooks se crean por la API, con POST /webhooks, o en la pestaña Webhooks del Developer Center, y para hacerlo hay que ser Org Admin o IT Developer Admin en Deel. Uno creado en el sandbox solo recibe eventos del sandbox.
Cómo se comprueba la firma
Deel calcula un HMAC-SHA256 de la palabra POST seguida del cuerpo tal cual llega, con la clave de firma del webhook, y pide comprobarlo antes de procesar nada. Esa clave (signing_key) la devuelve Deel al crear el webhook, y la genera él si no se le da una. Sus ejemplos de código sacan la firma en hexadecimal.
El controlador del conector hace el mismo cálculo con la clave guardada en la conexión, lo compara con x-deel-signature en tiempo constante y responde así:
| Lo que llega a Odoo | Respuesta |
|---|---|
| Firma buena | 200, con el evento apuntado en la cola |
| Sin firma o con una firma mala | 401 |
| Un token de dirección desconocido o un webhook desactivado en Odoo | 404 |
| Un cuerpo de más de 1 MB | 413 |
A diferencia del token de la API, que guarda FlexigoTech Cloud, la clave de firma se queda en Odoo, en la conexión, en un campo reservado a los administradores. Las pruebas del módulo comprueban la firma con el cálculo del ejemplo en Python de Deel, y contra la organización de demostración de Deel se probaron el alta y la baja del webhook.
Qué eventos hay
La página de eventos de Deel habla de más de 100 («100+ Events») y remite, para la lista completa, a GET /webhooks/events/types, que pide el permiso webhooks:read. En el índice de su referencia de la API, copiado el 18-11-2026, hay 56 eventos con página propia. En esa lista no hay ningún evento de factura emitida ni de informe bruto-neto: de facturas solo están los ajustes (Invoice Adjustment Created, Pending For Approval y Reviewed); de nóminas, los de nóminas disponibles de Global Payroll y de EOR y el de un documento de nómina borrado; y de pagos, el extracto iniciado y el marcado como pagado.
El conector se suscribe a 12, y cada uno solo le dice qué parte de la sincronización correr:
| Eventos de Deel | Lo que vuelve a leer el conector |
|---|---|
payment.statement.initiated, payment.statement.mark-paid | Los pagos |
invoice-adjustment.created, invoice-adjustment.reviewed, eor.payslips.available | Las facturas |
gp.payslips.available | La nómina de Global Payroll |
contract.created, contract.status.updated, contract.terminated, worker.v2.created, worker.v2.updated, worker.v2.deleted | Las personas y los contratos |
Un evento que el conector no conoce se apunta y se da por hecho sin correr nada.
Reintentos y desactivación, según Deel
Si la dirección no contesta con un 2xx, o tarda más de 30 segundos, Deel lo cuenta como fallo y reintenta con esperas de 1, 2, 4, 8, 16 y 32 minutos, luego de 1, 2 y 4 horas, y un décimo intento tras 16 horas. Con 10 fallos seguidos desactiva la suscripción, y hay que volver a activarla a mano, por la API o en el Developer Center. Deel pide contestar 200 en menos de 30 segundos, mejor en menos de 5, y avisa de que un mismo evento puede llegar más de una vez.
El conector contesta en cuanto apunta el evento; la sincronización viene después, en la cola. En Odoo, Webhook Activo solo se desmarca con Eliminar webhook o con Desconectar, y el conector no pregunta a Deel en qué estado está el webhook. Si Deel lo desactiva tras 10 fallos, por ejemplo porque Odoo estuvo caído, Odoo lo seguirá viendo activo: se reactiva en el Developer Center de Deel, o se elimina y se vuelve a registrar desde Odoo. Mientras tanto, la sincronización de cada 30 minutos sigue trayendo lo mismo. Para saber qué pasó con cada entrega, cada webhook tiene en el Developer Center una pestaña Logs con el código que devolvió tu Odoo; un 401 ahí apunta a la firma.
Qué hace el conector cuando suena
Deel llama directamente a tu Odoo, a una dirección https que lleva un token aleatorio de cada conexión, así que FlexigoTech Cloud no está en medio de la entrega. Por FlexigoTech Cloud pasan el alta y la baja del webhook y las lecturas que vienen después. Con la firma buena, Odoo apunta en la cola el tipo de evento, sin tomar el contenido como dato, y despierta la tarea Deel: cola de webhooks, que además corre sola cada hora. Esa tarea mira qué partes han sonado en cada conexión y corre cada una una sola vez, aunque hayan llegado varios avisos, leyendo otra vez de Deel por la API.

Cómo se da de alta desde Odoo
En la pestaña Webhooks de la conexión, un administrador pulsa Registrar webhook. El botón solo aparece si la conexión ya no está en No conectado (el token ya está guardado) y el webhook no está activo, y además hace falta:
- que Odoo esté en https, porque si no el conector se para y recuerda que «La sincronización programada sigue funcionando sin webhooks.»;
- que el token tenga
webhooks:write, el permiso que pide Deel para crear y para borrar un webhook; con un token solo de lectura, Deel responde 403 o 401, según su guía de autenticación. Con un 403, el conector enseña el motivo que da Deel; con un 401, dice que Deel rechazó el token y pide guardar uno nuevo, aunque al token solo le falte ese permiso.
El conector manda a Deel un nombre que empieza por Odoo, la dirección, los 12 eventos de la tabla y la versión v2 de la API, y guarda el identificador y la clave de firma que devuelve Deel. Si sale bien, avisa: «Deel llamará a Odoo cuando un pago, una nómina o un contrato cambie.» Eliminar webhook lo borra en Deel, y Desconectar también, si el servicio de FlexigoTech Cloud está activo.

Por qué además repasa cada 30 minutos
Deel recomienda no fiarse solo de los webhooks y repasar de vez en cuando. El conector lo hace con la tarea Deel: sincronizar contratos, facturas, pagos, nóminas y centros de costo, que corre cada 30 minutos haya webhooks o no. Y hay motivos de Deel para no quitarla: en su lista no hay un evento de factura emitida, así que las facturas nuevas llegan con ese repaso; un webhook que Deel desactiva no avisa a Odoo; y un Odoo sin https no puede recibirlos. Con webhooks, un pago, una nómina o un contrato llegan en cuanto Deel avisa; sin ellos, en la pasada siguiente.
Lo probado
Contra la organización de demostración de Deel (demo.deel.com), a través de FlexigoTech Cloud, se probaron la conexión, las entidades legales, un contrato con su persona y su proveedor, los webhooks y una segunda pasada sin duplicados. Facturas, pagos y ciclos de nómina se probaron con respuestas hechas sobre la referencia de la API de Deel, porque esa organización aún no tenía. El conector funciona en Odoo 17, 18, 19 y 20, en tu servidor o en Odoo.sh, y no en Odoo Online. El token y sus permisos están en la guía del Deel API token, y lo que entra como factura de proveedor, en Deel invoice. El conector está explicado entero en su página y publicado en Odoo Apps.
Sigue leyendo
Comprobado en el código del conector (versión 20.0) y en las fuentes enlazadas
Fuentes
- 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 del módulo: flexigo_deel_connector 20.0 (18442307): models/deel_account.py
- Código del módulo: flexigo_deel_connector 20.0 (18442307): controllers/main.py
- Código del módulo: flexigo_deel_connector 20.0 (18442307): data/deel_cron.xml
- Código del módulo: flexigo_deel_connector 20.0 (18442307): static/description/index.html
- Código del 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 del módulo: flexigo_deel_connector 20.0 (18442307): views/deel_account_views.xml
