Webhook é o mecanismo que permite que sejam construídos aplicativos integrados ao ERP Varejonline que se subscrevam em certos eventos do sistema. Quando esses eventos forem disparados, seja por interação manual ou automática, nós enviamos um HTTP/HTTPS POST para a url configurada no webhook do evento.

O webhook pode ser utilizado para que sejam recebidas notificações de alteração, criação e remoção de objetos que possuam API na Varejonline.

Para subscrever seu aplicativo em algum evento, uma nova API de manutenção de webhooks foi criada. Nela, é possível criar, alterar e remover webhooks. Cada webhook tem como escopo a base Varejonline do token de acesso utilizado em sua configuração. Ou seja, ao se subscrever em um webhook com determinado token de acesso, obtido via oauth, o aplicativo será notificado sobre as modificações realizadas na base Varejonline do usuário associado ao token.

Deve ser utilizado o mesmo procedimento para consumo de qualquer endpoint da API Varejonline. Para manutenção dos webhooks, foram disponibilizados quatro endpoints (GET, POST, PUT e DELETE) no endereço: https://integrador.varejonline.com.br/apps/api/webhook

Eventos Disponíveis:

Tipos de Notificação:

Ao cadastrar ou alterar um webhook, o atributo types deve ser um array de string com as seguintes opções:

• POST - Notifica a criação de novos objetos do evento associado
• PUT - Notifica a atualização de objetos do evento associado
• DELETE - Notifica a remoção de objetos do evento associado

URL: https://integrador.varejonline.com.br/apps/api/webhook/:id

Utilizado para obter um webhook previamente cadastrado.

Parâmetros:

• id: Identificador do webhook buscado (GUID String - Path Param).

Retorno: Retorna um JSON com as informações do webhook buscado:

• uuid: Define o id de negócio do hook (String).
• event: Evento associado ao Webhook (String).
• types: Operações que serão notificadas (POST, PUT, DELETE) (Array String).
• url: Endereço completo que será notificado ao ser disparada a operação no evento configurados no Webhook (String).

Exemplo de Retorno:

{
   "url":"http://seudominio.com.br/notification/event/produto",
   "event":"PRODUTOS",
   "uuid":"183661dc-376f-4aef-afeb-d41633c64f2d",
   "types":[
      "POST",
      "PUT"
   ]
}

URL: https://integrador.varejonline.com.br/apps/api/webhook

Content-Type = application/json

Utilizado para cadastrar um novo webhook em uma base Varejonline

Atenção: Após cadastro, pode levar até 30 minutos para que este webhook comece a ser notificado dos eventos.

Parâmetros - JSON Body:

• event: Evento associado ao Webhook (String).
• types: Operações que serão notificadas (POST, PUT, DELETE) (Array String).
• url: Endereço completo que será notificado ao ser disparada a operação no evento configurados no Webhook (String).

Retorno: Retorna um JSON com informações sobre o resultado da operação realizada, contendo:

• idRecurso: Identificador do webhook gerado (GUID String). Cada notificação enviada para o webhook carregará esse identificador. Dessa forma, você saberá porque está sendo notificado e de qual base é a notificação, uma vez que o token utilizado está amarrado a base.
• codigoMensagem: Código de identificação da operação realizada. [veja a lista de Códigos] (Retorno-API)
• mensagem: Mensagem da operação realizada

Exemplo de Envio:

{
   "url":"http://seudominio.com.br/notification/event/produto",
   "event":"PRODUTOS",
   "types":[
      "POST",
      "PUT"
   ]
}

URL: https://integrador.varejonline.com.br/apps/api/webhook/:id

Content-Type = application/json

Utilizado para editar um webhook em uma base Varejonline

Parâmetros - JSON Body:

• uuid: Identificador do webhook (GUID String).
• event: Evento associado ao Webhook (String).
• types: Operações que serão notificadas (POST, PUT, DELETE) (Array String).
• url: Endereço completo que será notificado ao ser disparada a operação no evento configurados no Webhook (String).

Retorno: Retorna um JSON com informações sobre o resultado da operação realizada, contendo:

• idRecurso: uuid do webhook atualizado. Este uuid será atualizado na manutenção do Webhook, gerando um novo código (String).
• codigoMensagem: Código de identificação da operação realizada. [veja a lista de Códigos] (Retorno-API)
• mensagem: Mensagem da operação realizada

Exemplo de Envio:

{
   "url":"http://seudominio.com.br/notification/event/produto",
   "event":"PRODUTOS",
   "uuid":"5b19c9ee-1e9f-4033-899b-676a9239f241",
   "types":[
      "POST",
      "PUT"
   ]
}

URL: https://integrador.varejonline.com.br/apps/api/webhook/:id

Utilizado para remover um webhook em uma base Varejonline e assim, deixar de ser notificado sobre ocorrências nos objetos associados ao evento.

Parâmetros:

• id: Identificador do webhook (GUID String - Path Param).

Ao serem disparadas ocorrências sobre os objetos associados aos eventos configurados, será enviado um JSON no corpo de uma requisição POST à URL configurada. Este JSON possui os dados do objeto e o tipo da ocorrência, bem como o uuid do webhook associado ao comunicado.

Lembre-se: Com o uuid é possível saber de qual base Varejonline é o evento, pois no momento do seu cadastro e atualização, um token de acesso de uma base específica foi utilizado, e um webhook tem escopo de uma base. Portando, caso queira receber notificações de certo evento de todas as bases dos clientes que utilizam seu aplicativo, cadastre um webhook para cada base Varejonline, utilizando o respectivo token de acesso.

As notificações são realizadas por meio de retransmissão em caso de falhas. Elas ocorrem da seguinte forma:

• Primeira retransmissão em 5 minutos
• Segunda retransmissão em 45 minutos
• Terceira retransmissão em 90 minutos
• Quarta retransmissão em 120 minutos

Se persistir a falha, o evento é descartado.

Estrutura da Notificação

• object: URL da API Varejonline do objeto modificado.
• webhookEvent: Evento disparado.
• eventType: Tipo do gatilho disparado. Define se foi uma criação, atualização ou remoção do objeto.
• contractId: UUID do cadastro do webhook para o evento disparado.

Exemplo de Notificação:

{
  "object": "https://erp.varejonline.com.br/apps/api/produtos/24",
  "webhookEvent": "PRODUTOS",
  "eventType": "PUT",
  "contractId": "7c338e4e-da84-45c5-93db-cadac036c5e0"
}

Após registrar ou alterar o endereço de um webhook, aguarde 30 minutos para sua atualização no barramento.