Webhooks¶

Aviso

É altamente recomendável consultar um desenvolvedor, arquiteto de soluções ou outra função técnica ao decidir usar webhooks e durante todo o processo de implementação. Se não forem configurados corretamente, os webhooks podem interromper a base de dados do Odoo e levar tempo para serem revertidos.

Webhooks, que podem ser criados no Odoo Studio, permitem automatizar uma ação no seu banco de dados Odoo quando um evento específico ocorre em outro sistema externo.

Na prática, isso funciona da seguinte forma: quando o evento ocorre no sistema externo, um arquivo de dados (o “payload”) é enviado para a URL do webhook do Odoo por meio de uma solicitação de API POST, e uma ação predefinida é executada no seu banco de dados Odoo.

Diferentemente de ações agendadas, que são executadas em intervalos predefinidos, ou solicitações de API manuais, que precisam ser explicitamente invocadas, webhooks permitem comunicação e automação em tempo real, orientadas por eventos. Por exemplo, você pode configurar um webhook para que seus dados de Inventário do Odoo sejam atualizados automaticamente quando um Pedido de venda for confirmado em um sistema de ponto de venda externo.

Configurar um webhook no Odoo não requer codificação ao conectar dois bancos de dados Odoo, mas testar um webhook requer uma ferramenta externa. Registros de destino ou ações personalizadas podem exigir habilidades de programação.

Nota

Este artigo aborda a criação de um webhook que recebe dados de uma fonte externa. No entanto, também é possível criar uma ação automatizada que envia dados para um webhook externo quando ocorre uma alteração no seu banco de dados Odoo.

Criar um webhook no Odoo¶

Importante

Antes de implementar um webhook em um banco de dados ativo, configure e teste-o usando um banco de dados duplicado para garantir que o webhook funcione conforme o esperado.

Dica

Ativar o modo de desenvolvedor antes de criar um webhook oferece maior flexibilidade na seleção do modelo que a regra de automação tem como alvo. Também permite encontrar o nome técnico do modelo e dos campos, que podem ser necessários para configurar o payload.

Para encontrar o nome técnico de um modelo, com o modo de desenvolvedor ativado, passe o mouse sobre o nome do modelo e clique em (Link interno). O nome técnico pode ser encontrado no campo Modelo. Por exemplo, um webhook de pedido de venda usa o modelo Pedido de venda, mas o nome técnico sale.order é usado no payload.

Para criar um webhook no Estúdio, proceda da seguinte forma:

Abra o Estúdio e clique em Webhooks, depois em Novo.
Dê ao webhook um nome claro e significativo que identifique sua finalidade.
Se necessário, e desde que o modo de desenvolvedor esteja ativado, selecione o Modelo apropriado no menu suspenso. Se o modo de desenvolvedor não estiver ativado, a regra de automação tem como alvo o modelo atual por padrão.
A URL do webhook é gerada automaticamente, mas pode ser alterada, se necessário, clicando em Girar segredo. Esta é a URL que deve ser usada ao implementar o webhook no sistema externo que enviará atualizações para o banco de dados.

Aviso
A URL é confidencial e deve ser tratada com cuidado. Compartilhá-la online ou sem cautela pode fornecer acesso não intencional ao banco de dados Odoo. Se a URL for atualizada após a implementação inicial, certifique-se de atualizá-la no sistema externo.
Se desejar, ative Registrar chamadas para rastrear o histórico de solicitações de API feitas para a URL do webhook, por exemplo, para fins de solução de problemas.
Se o sistema que envia o webhook não for o Odoo, ajuste o código de Registro de destino para procurar o registro JSON incluído no payload quando a solicitação de API for feita para a URL do webhook. Se o sistema que envia o webhook for um banco de dados Odoo, certifique-se de que id e model apareçam no payload.

Se o webhook for usado para criar registros no banco de dados Odoo, use model.browse(i) ou model.search(i) em vez do formato padrão de Registro de destino.
Clique em Adicionar uma ação na aba Ações a fazer para definir as ações a serem executadas.
Antes de implementar o webhook no sistema externo, teste-o para garantir que funcione conforme o esperado.

Dica

Webhooks também podem ser criados por meio do menu Automações no Estúdio, selecionando o gatilho No webhook.
Para acessar o histórico de solicitações de API se Registrar chamadas foi ativado, clique no botão inteligente Logs no topo do formulário Regras de automação.
Se o propósito do webhook for algo diferente de atualizar um registro existente, por exemplo, criar um novo registro, a ação Executar Código deve ser escolhida.

Testar um webhook¶

Testar um webhook requer uma carga de teste e uma ferramenta ou sistema externo, como Postman, para enviar a carga por meio de uma solicitação de API POST. Esta seção apresenta as etapas para testar um webhook no Postman.

Dica

Consulte a seção de casos de uso de webhook para explicações passo a passo de como testar webhooks usando cargas de teste.
Para obter ajuda específica com o teste de um webhook com o Postman, entre em contato com a equipe de suporte deles.

No Postman, crie uma nova solicitação HTTP e defina seu método como POST.
Copie a URL do webhook do seu banco de dados Odoo usando o ícone (link) e cole-a no campo URL no Postman.
Clique na aba Body e selecione raw.
Defina o tipo de arquivo como JSON, depois copie o código da carga de teste e cole-o no editor de código.
Clique em Enviar.

No visualizador de Resposta na parte inferior da tela no Postman, os detalhes, incluindo um código de resposta HTTP, indicam se o webhook está funcionando corretamente ou não.

Uma mensagem 200 OK ou status: ok indica que o webhook está funcionando adequadamente do lado do Odoo. A partir daqui, a implementação pode começar com o outro sistema para enviar automaticamente as solicitações de API para a URL do webhook do Odoo.
Se qualquer outra resposta for retornada, o número associado a ela ajuda a identificar o problema. Por exemplo, uma mensagem 500 Internal Server Error significa que o Odoo não pôde interpretar a chamada adequadamente. Neste caso, certifique-se de que os campos encontrados no arquivo JSON estão devidamente mapeados na configuração do webhook e no sistema que envia a chamada de teste.

Dica

Ativar o registro de chamadas na configuração do webhook no Odoo fornece logs de erro se o webhook não estiver funcionando como pretendido.

Implementar um webhook em um sistema externo¶

Quando o webhook tiver sido criado com sucesso no Odoo e testado, implemente-o no sistema que envia dados para o banco de dados Odoo, certificando-se de que as solicitações de API POST sejam enviadas para a URL do webhook.

Casos de uso de webhooks¶

Abaixo estão dois exemplos de como usar webhooks no Odoo. Uma carga de teste é fornecida para cada exemplo e pode ser encontrada na seção sobre teste do webhook. O Postman é usado para enviar a carga de teste.

Atualizar a moeda de um pedido de vendas¶

Este webhook atualiza um pedido de venda no aplicativo Vendas para USD quando o sistema externo envia uma solicitação de API POST para a URL do webhook que inclui esse número de pedido de venda (que é identificado pelo registro id da carga).

Isso pode ser útil para subsidiárias fora dos Estados Unidos com uma empresa matriz localizada dentro dos Estados Unidos ou durante fusões ao consolidar dados em um banco de dados Odoo.

Criar o webhook¶

Para criar este webhook, proceda da seguinte forma:

Abra o aplicativo Vendas, depois abra o Estúdio e clique em Webhooks. O modelo Pedido de venda é selecionado por padrão.
Clique em Novo. O Gatilho é definido como No webhook por padrão.
Defina o Registro de destino como model.env[payload.get('_model')].browse(int(payload.get('_id'))), onde:
- payload.get('_model') recupera o valor associado à chave model no payload, ou seja, sale.order, que é o nome técnico do modelo Pedido de venda.
- payload.get('_id') recupera o valor associado à chave id no payload, ou seja, o número do pedido de venda de destino no seu banco de dados Odoo com o S e os zeros à esquerda removidos.
- int converte o id recuperado em um número inteiro (ou seja, um número inteiro) porque o método browse() só pode ser usado com um número inteiro.
Clique em Adicionar uma ação.
Na seção Tipo, clique em Atualizar registro.
Na seção Detalhes da ação, selecione Atualizar, escolha o campo Moeda e selecione USD.
Clique em Salvar e fechar.

Testar o webhook¶

Para testar este webhook, proceda da seguinte forma:

Com o Postman aberto, crie uma nova solicitação HTTP e defina seu método como POST.
Copie a URL do webhook Odoo usando o ícone (link) e cole-a no campo URL no Postman.
Clique na aba Body e selecione raw.
Defina o tipo de arquivo como JSON, depois copie este código, ou seja, o payload, e cole-o no editor de código:
```
{
    "_model": "sale.order",
    "_id": "SALES ORDER NUMBER"
}
```
No seu banco de dados Odoo, escolha um pedido de venda para testar o webhook. No código colado, substitua SALES ORDER NUMBER pelo número do pedido de venda sem o S ou quaisquer zeros antes do número. Por exemplo, um pedido de venda com o número S00007 deve ser inserido como 7 no Postman.
Clique em Enviar.
Consulte o Visualizador de resposta no Postman para determinar se o webhook está funcionando corretamente ou não. Se uma mensagem diferente de 200 OK ou status: ok for retornada, o número associado à mensagem ajuda a identificar o problema.

Criar um novo contato¶

Este webhook usa código personalizado para criar um novo contato em um banco de dados Odoo quando o sistema externo envia uma solicitação de API POST para a URL do webhook que inclui as informações do contato. Isso pode ser útil para criar automaticamente novos fornecedores ou clientes.

Criar o webhook¶

Para criar este webhook, proceda da seguinte forma:

Abra o aplicativo Contatos, depois abra o Estúdio e clique em Webhooks. O modelo Contato é selecionado por padrão.
Clique em Novo. O Gatilho é definido como No webhook por padrão.
Defina o Registro de destino como model.browse([2]). Isso é essencialmente um espaço reservado, pois o código na ação automatizada diz ao webhook o que precisa ser recuperado do payload e em qual modelo o registro precisa ser criado.
Clique em Adicionar uma ação.
Na seção Tipo, clique em Executar Código.

Copie este código e cole no editor de código na aba Código da seção Detalhes da Ação:

# variables to retrieve and hold data from the payload
contact_name = payload.get('name')
contact_email = payload.get('email')
contact_phone = payload.get('phone')

# a Python function to turn the variables into a contact in Odoo
if contact_name and contact_email:
    new_partner = env['res.partner'].create({
        'name': contact_name,
        'email': contact_email,
        'phone': contact_phone,
        'company_type':'person',
        'customer_rank': 1,
    })
# an error message for missing required data in the payload
else:
    raise ValueError("Missing required fields: 'name' and 'email'")

Clique em Salvar e fechar.

Testar o webhook¶

Para testar este webhook, proceda da seguinte forma:

No Postman, crie uma nova requisição HTTP e defina seu método como POST.
Copie a URL do webhook Odoo usando o ícone (link) e cole-a no campo URL no Postman.
Clique na aba Body e selecione raw.

Defina o tipo de arquivo como JSON, depois copie este código, ou seja, o payload, e cole-o no editor de código:

{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}

No código colado, substitua CONTACT NAME, CONTACTEMAIL@EMAIL.COM e CONTACT PHONE NUMBER pelas informações de um novo contato.
Clique em Enviar.
Consulte o Visualizador de resposta no Postman para determinar se o webhook está funcionando corretamente ou não. Se uma mensagem diferente de 200 OK ou status: ok for retornada, o número associado à mensagem ajuda a identificar o problema.

Editar no GitHub