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.

Os webhooks, que podem ser criados no Estúdio, são regras de automação acionadas por eventos externos por meio de retornos de chamada HTTP definidos pelo usuário. Quando um sistema externo envia dados para a URL de um webhook do Odoo (o “gatilho”) com um arquivo de dados (a “carga útil”), o Odoo responde com uma ação predefinida no banco de dados.

Diferentemente das ações agendadas ou das chamadas manuais à API, os webhooks permitem a comunicação e a automação em tempo real. Por exemplo, se um pedido de vendas for confirmado em um sistema de PDV externo, um webhook pode atualizar instantaneamente o inventário do Odoo, garantindo a sincronização do sistema.

Nota

Este artigo aborda a criação de um webhook que recebe dados de uma fonte externa. Entretanto, também é possível criar uma ação automatizada que envia uma chamada de API para um webhook externo.

Criar um webhook no Estúdio¶

Os webhooks são configurados no Estúdio e sua configuração é dividida entre seu disparo e suas açõe.

Dica

A configuração de um webhook no Odoo não requer codificação ao conectar bases de dados do Odoo, mas o teste requer uma ferramenta externa, como o Postman. Registros ou ações de destino personalizados podem exigir habilidades de programação.
Ative o modo de desenvolvedor para modificar o modelo visado pelo webhook (por exemplo, pedidos de vendas ou informações de contato) e para encontrar o nome técnico do modelo (que pode ser necessário para a configuração adequada da carga útil).

Definir o disparo do webhook¶

Para criar um webhook com o Estúdio, abrir o Studio, clique em Webhooks e, em seguida, em Novo. A partir daqui, nomeie o webhook, modifique o modelo do webhook (o tipo de entrada de banco de dados a ser direcionada), se necessário, e alterne se as chamadas feitas para o URL do webhook devem ser registradas (o que rastrearia o histórico de chamadas do webhook para solução de problemas).

O URL do webhook é gerado automaticamente. Esse é o URL que deve ser usado para testar o webhook e conectá-lo ao sistema externo que enviará atualizações à base de dados.

Perigo

O URL do webhook é confidencial e deve ser tratado com cuidado. Compartilhá-lo on-line ou sem cautela pode fornecer acesso não intencional ao banco de dados do Odoo. Clique em Alternar segredo para alterar a URL, se necessário.

Por fim, se o sistema que envia o webhook não for o Odoo, ajuste as ações Registro-alvo para procurar o registro JSON que está incluído no payload da chamada de API quando a chamada é feita para o URL do webhook. Se o sistema que está enviando o webhook for uma base de dados do Odoo, certifique-se de que o id e o model apareçam na carga.

Dica

Embora o Modelo esteja definido no Odoo, é o nome técnico do modelo que deve ser incluído no payload. Passe o mouse sobre o nome do modelo e clique no ícone (Internal link) para localizar esse nome técnico no campo Modelo. Por exemplo, um webhook de pedido de vendas usa o modelo Pedido de venda, mas o nome técnico sale.order é usado na carga útil.

Nota

Ao criar um registro na base de dados do Odoo, o formato padrão do registro de destino não deve ser usado. Em vez disso, use model.browse(i) ou model.search(i).

Definir a ação do webhook¶

Para definir a ação de um webhook durante a configuração de um webhook, clique em Adicionar uma ação na aba Ação a fazer. Clique no Tipo da ação e defina os campos conforme necessário.

Testar o webhook¶

Nota

Testar o webhook requer a configuração do webhook, uma carga útil de teste para enviar ao webhook e uma ferramenta ou sistema externo para enviar a carga útil por meio de uma solicitação de API POST. Considere o uso de uma ferramenta como o Postman para que sejam necessárias menos habilidades técnicas.

Se uma mensagem dizendo 200 OK ou status: ok for retornada durante o teste, então o webhook está funcionando corretamente no lado do Odoo. A partir disso, é possível começar a implementação com a outra ferramenta, para enviar automaticamente essas chamadas de webhook para o Odoo usando o URL do webhook.

Se qualquer outra resposta for retornada, o número enviado na resposta ajudará a identificar o problema. Por exemplo, um 500 Internal Server Error significa que o Odoo não conseguiu interpretar a chamada corretamente. Se isso for retornado, verifique se os campos encontrados no arquivo JSON estão mapeados corretamente na configuração do webhook e no sistema que está enviando a chamada de teste. A ativação do registro de chamadas na configuração do webhook fornece registros de erros se o webhook não estiver funcionando como pretendido.

Implementar o webhook¶

Quando o webhook estiver totalmente configurado, comece a conectá-lo ao sistema que envia dados para a base de dados do Odoo por meio desse webhook. Certifique-se de que as chamadas de API sejam enviadas para o URL do webhook ao configurar esse sistema.

Casos de uso de webhooks¶

Abaixo, há dois exemplos de como usar webhooks no Odoo. Esses webhooks exigem ferramentas externas (que estão listadas no exemplo).

Aviso

Consulte um desenvolvedor, arquiteto de soluções ou outra função técnica ao decidir implementar webhooks. Se não forem configurados corretamente, os webhooks podem interromper oa base de dados do Odoo e podem levar tempo para serem revertidos.

Atualizar a moeda de um pedido de vendas¶

Esse webhook atualiza um pedido de vendas no aplicativo Vendas para USD. É útil para subsidiárias fora dos Estados Unidos com uma empresa-mãe localizada dentro dos Estados Unidos ou durante fusões ao consolidar dados em uma base de dados Odoo.

Definir o disparo do webhook¶

Para configurar esse webhook, abra o aplicativo Vendas. Em seguida, configure o acionador para que o Modelo seja definido como Pedido de Venda. Além disso, defina o Registro-alvo como model.env[payload.get('model')].browse(int(payload.get('id'))). Isso está detalhado abaixo.

model: o que é atualizado no Odoo (neste caso, pedidos de vendas). Corresponde ao Modelo definido anteriormente.
env: onde a ação ocorre. Nesse caso, é o Odoo.
payload: o que é enviado para o URL do webhook. Contém as informações que atualizam o pedido de vendas.
get(‘model’): informa ao webhook qual registro da base de dados deve ser consultado. Nesse caso, o webhook recupera (get) os dados vinculados a um model específico. Neste exemplo, esse é o modelo Pedido de Venda.
browse: informa ao webhook para procurar no modelo (Pedido de Venda) definido pelo payload o que deve ser atualizado.
int: transforma o alvo em um integer (um número inteiro). Isso é importante no caso de algumas palavras (uma string) ou números decimais serem incluídos no registro de destino do payload.
get(‘id’): identifica o número do pedido de vendas que está sendo atualizado no Odoo.

Definir a ação do webhook¶

Após definir o acionador, defina a ação do webhook clicando em Adicionar uma ação. Para o Tipo, clique em Atualizar registro. Em seguida, selecione Atualizar, escolha o campo Moeda e selecione USD para que o campo de moeda seja atualizado para USD. Por fim, clique em Salvar e Fechar.

Resumo da configuração do webhook¶

Para resumir o que está configurado, o webhook tem como alvo os pedidos de vendas, identificados pelo número do pedido de vendas, e atualiza a moeda para USD quando uma solicitação POST é enviada ao URL do webhook que inclui o número do pedido de vendas (que é identificado pelo registro id do payload).

Testar o webhook¶

Teste a configuração do webhook para ter certeza de que tudo está correto. Esse processo usa uma ferramenta chamada Postman para enviar o disparo simulado.

Esta seção apresenta as etapas para testar esse webhook no Postman, mas não oferece ajuda se houver algum problema com essa ferramenta. Para obter ajuda específica com o Postman, entre em contato com a equipe de suporte.

Quando o Postman estiver aberto, crie uma nova solicitação HTTP e defina seu método como POST. Em seguida, copie o URL do webhook que está sendo testado e cole-o no campo URL do Postman. Depois disso, clique na aba Conteúdo e selecione a opção bruto. Defina o tipo de arquivo como JSON e, em seguida, copie este código e cole-o no arquivo.

{
    "model": "sale.order",
    "id": "SALES ORDER NUMBER"
}

A partir daqui, escolha um pedido de vendas para testar o webhook. Se não for possível testar em uma base de dados ativo do Odoo, considere criar uma base de dados de demonstração com uma amostra de pedido de vendas e o webhook que foi configurado. Substitua NÚMERO DO PEDIDO DE VENDA pelo número do pedido de venda sem o S ou zeros antes do número. Por exemplo, um pedido de venda com o número S00007 deve ser inserido como 7 no Postman. Por fim, clique em Enviar no Postman.

Se uma mensagem dizendo 200 OK ou status: ok for retornada, então o webhook está funcionando corretamente no lado do Odoo. A moeda do pedido de vendas de teste é atualizada. A partir daqui, a implementação pode começar com a outra ferramenta para enviar automaticamente essas chamadas de webhook para o Odoo usando o URL do webhook.

Se outras respostas forem retornadas, o número associado a elas ajudará a identificar o problema. Por exemplo, um 500 Internal Server Error significa que o Odoo não conseguiu interpretar a chamada corretamente. Se isso for retornado, verifique se os campos model e id estão mapeados corretamente na configuração do webhook e no Postman.

Criar um novo contato¶

Esse webhook usa código personalizado para criar um novo contato em uma base de dados Odoo. Isso pode ser útil para criar novos fornecedores ou clientes automaticamente.

Definir o disparo do webhook¶

Para configurar esse webhook, abra o aplicativo Contatos. Em seguida, configure o acionador para que o Modelo seja definido como Contato. Além disso, defina o Registro-alvo como model.browse([2]). Isso está detalhado abaixo.

model: o que é atualizado no Odoo (neste caso, um contato). Corresponde ao Modelo definido anteriormente.
browse: diz ao webhook para procurar no modelo (os contatos) definido pelo payload o que criar.

Definir a ação do webhook¶

Depois de definir o disparo, defina a ação do webhook clicando em Adicionar uma ação. Para o Tipo, clique em Executar código e, em seguida, defina o código como o código de exemplo abaixo. Por fim, clique em Salvar e Fechar.

# 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'")

Resumo da configuração do webhook¶

Para resumir o que está configurado, o webhook cria um contato quando uma chamada de API é enviada para o URL do webhook que inclui as informações do contato.

Testar o webhook¶

Teste a configuração do webhook para ter certeza de que tudo está correto. Esse processo usa uma ferramenta chamada Postman para enviar o disparo simulado.

Após abrir o Postman, crie uma nova solicitação e defina seu método como POST. Em seguida, copie o URL do webhook que está sendo testado e cole-o no campo URL do Postman. Depois disso, clique na aba Conteúdo e clique em bruto. Defina o tipo de arquivo como JSON e, em seguida, copie este código e cole-o no arquivo.

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

Substitua os campos acima pelas informações de um novo contato no Postman e, em seguida, clique em Enviar.

Se uma mensagem dizendo 200 OK ou status: ok for retornada, então o webhook está funcionando corretamente no lado do Odoo. O novo contato de teste aparece no aplicativo Contatos. A partir disso, a implementação pode começar com a outra ferramenta, para enviar automaticamente essas chamadas de webhook para o Odoo usando a URL do webhook.

Se outras respostas forem retornadas, o número associado a elas ajudará a identificar o problema. Por exemplo, um 500 Internal Server Error significa que o Odoo não conseguiu interpretar a chamada corretamente. Se isso for retornado, verifique se os campos encontrados no arquivo JSON estão mapeados corretamente na configuração do webhook e no Postman.

Edit on GitHub