Webhooks

Webhooks são um meio de uma aplicação fornecer informações em tempo real para outras aplicações em resposta a eventos ou acionadores específicos. Eles são úteis para notificar outras aplicações sobre eventos importantes, como a criação de um novo pedido ou a atualização de um produto em tempo real.

Nota

Ao criar uma aplicação, o integrador deve informar a URL que estará escutando nossas notificações. Os escopos selecionados no momento da criação da aplicação definirão em quais tópicos ela receberá notificações. Por exemplo, caso tenha selecionado portfolio:write, enviaremos uma notificação quando um produto é criado.

Formato Padrão das Mensagens de Webhook

Quando um evento ocorre no sistema, enviamos uma notificação para a URL de callback configurada. A notificação é enviada no formato JSON com a seguinte estrutura:

{
  "data": {
    "domain": "order.order",
    "status": "new|approved|cancelled|finished",
    "order_id": "<order id>",
    "delivery_id": "<delivery id>"
  }
}

Descrição dos Campos

data: Objeto que contém as informações detalhadas sobre o evento.
domain: Indica o domínio ou categoria do evento, definindo o contexto da notificação. Os valores possíveis são:
- order: Relacionado a pedidos e entregas, podendo ser subdividido em:
  - order.order: Relacionado a pedidos.
  - order.delivery: Relacionado a entregas (Eu Preciso Entregas).
  - order.shipping: Relacionado a envios (entrega a combinar).
- portfolio: Relacionado a portfólio de produtos. Está subdividido em:
  - portfolio.sku: Relacionado a unidades de manutenção de estoque (Stock Keeping Units).
  - portfolio.ad: Relacionado a anúncios.
  - portfolio.price: Relacionado a alterações de preço.
  - portfolio.inventory: Relacionado ao estoque disponível.
- chat: Relacionado a mensagens ou interações via chat.
- ticket: Relacionado a tickets de suporte ou atendimento ao cliente.
status: Indica o estado atual ou a ação realizada no domínio especificado. Os valores possíveis variam conforme o domínio:
- Para order.order:
  - approved: Pedido aprovado.
  - cancelled: Pedido cancelado.
  - finished: Pedido concluído.
- Para order.delivery:
  - created: Entrega/Etiqueta gerada.
  - received: Pedido coletado.
  - posted: Pedido enviado.
  - delivered: Pedido entregue.
- Para order.shipping:
  - shipped: Pedido enviado.
  - delivered: Pedido entregue.
- Para portfolio.sku:
  - created: Novo SKU criado. O sistema não permite a modificação direta dos dados de um registro existente. Isso significa que, sempre que for necessária alguma alteração em um SKU, é obrigatório criar um novo registro para ele, por essa razão o status de sku será sempre created.
- Para portfolio.ad:
  - created: Anúncio criado.
  - updated: Anúncio atualizado.
  - highlighted: Anúncio destacado.
- Para portfolio.price:
  - created: Preço criado.
  - updated: Preço alterado.
- Para portfolio.inventory:
  - created: Estoque criado.
  - updated: Estoque atualizado. Quando o campo quantity se mantiver inalterado.
  - increased: Estoque aumentado.
  - decreased: Estoque diminuído.
- Para chat:
  - new_conversation: Nova conversa.
  - message_received: Mensagem recebida.
- Para ticket:
  - opened: Ticket aberto.
  - closed: Ticket fechado.
  - updated: Ticket atualizado.
id: Identificador único do recurso afetado pelo evento (por exemplo, ID do pedido ou SKU).
code: Código associado ao recurso, como o código do pedido ou do produto.

Exemplo de Notificação para Pedido

{
  "data": {
    "domain": "order",
    "status": "new",
    "id": "123456",
    "code": "ABC123"
  }
}

Como Utilizar as Informações da Notificação

Identificação do Evento: Utilize o campo domain para identificar o tipo de recurso afetado e o campo status para entender a ação que ocorreu.
Processamento Adequado: Baseado no domain e status, execute as ações necessárias em sua aplicação, como atualizar um pedido no seu sistema ou ajustar o estoque.
Manutenção de Sincronização: Use os campos id e code para garantir que está atualizando o recurso correto em seu sistema.

Observações Importantes

Flexibilidade de Domínios: O campo domain permite que sua aplicação trate diferentes tipos de eventos de forma modular.
Atualizações Futuras: Este formato facilita a adição de novos domínios e status no futuro, garantindo escalabilidade.
Segurança: Certifique-se de validar e sanitizar todas as informações recebidas antes de processá-las.

Como garantir a autenticidade das notificações?

Para garantir que as notificações enviadas sejam autênticas, usamos o algoritmo HMAC-SHA256. O HMAC (Hash-based Message Authentication Code) é uma maneira de verificar a integridade e autenticidade de uma mensagem, utilizando uma chave secreta compartilhada entre o remetente (no caso, a nossa aplicação) e o receptor (o integrador).

Funcionamento do HMAC-SHA256

Quando enviamos uma notificação para a sua URL de callback, incluímos no cabeçalho um valor chamado X-EP-Signature. Esse valor é gerado aplicando-se o algoritmo HMAC-SHA256 ao corpo da requisição, utilizando o access_token do cliente como chave criptográfica. Isso gera um hash que é enviado junto com a requisição. O hash é gerado da seguinte forma:

Corpo da requisição: O conteúdo da notificação em formato JSON.
access_token: Chave secreta compartilhada entre a nossa aplicação e o integrador.
Algoritmo HMAC-SHA256: Um algoritmo de hash seguro que usa uma chave secreta para gerar um hash do corpo da mensagem.
Digest: A saída do hash é codificada em Base64.

Após gerar o hash, o resultado é incluído no cabeçalho X-EP-Signature.

Verificação no Lado do Integrador

No lado do integrador, você deve seguir este processo para verificar se a notificação é autêntica:

Gerar o Hash: Gere um hash utilizando o mesmo algoritmo HMAC-SHA256 com o corpo da requisição recebida e o access_token configurado na sua aplicação.
Codificar em Base64: Utilize o método .digest('base64') para gerar o hash no formato correto.
Comparar: Compare o hash gerado com o valor recebido no cabeçalho X-EP-Signature.
Se os dois valores coincidirem, a requisição é considerada autêntica.

Exemplo Prático de Verificação de HMAC com Digest base64

Suponha que você recebeu a seguinte notificação:

{
  "data": {
    "domain": "order",
    "status": "new",
    "id": "123456",
    "code": "ABC123"
  }
}

E o cabeçalho contém o valor X-EP-Signature:

X-EP-Signature: FsZGVzay1zaWduYXR1cmU=

Passos para Verificar a Assinatura

Corpo da Requisição: O JSON acima, serializado em uma string.
Chave: O access_token configurado na sua aplicação.
Algoritmo HMAC-SHA256: Utilize uma biblioteca de criptografia para gerar o hash, com digest em Base64.

Exemplo:

import crypto from 'crypto';
 
const secret = process.env.ACCESS_TOKEN;
const rawBody = JSON.stringify(req.body);
 
const generatedHash = crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('base64');
 
console.log(generatedHash);
 
// Comparar com o valor recebido no cabeçalho X-EP-Signature
 
if (generatedHash === req.headers['X-EP-Signature']) {
  console.log('Assinatura válida. A requisição é autêntica.');
} else {
  console.log('Assinatura inválida. A requisição pode não ser autêntica.');
}

Configuração da URL de Callback

Para configurar ou atualizar a URL de callback para receber notificações de webhooks, utilize o seguinte endpoint:

https://apps.eupreciso.com.br/v1.0/marketplace/webhooks/url

Métodos de Requisição

POST: Cria ou atualiza a URL de callback para receber notificações de webhooks.
GET: Retorna a URL de callback configurada para receber notificações de webhooks.
DELETE: Remove a URL de callback configurada para receber notificações de webhooks.

Cabeçalhos da Requisição

authorization: Bearer access_token
O access_token do anunciante deve ser incluído no header de autorização seguindo o padrão OAuth 2.0.

Corpo da Requisição

{
  "url": "https://integrador.com.br/webhook"
}

Respostas

200 OK: A operação foi bem-sucedida.
400 Bad Request: Requisição inválida (por exemplo, URL malformada).
401 Unauthorized: Token de acesso inválido ou ausente.
500 Internal Server Error: Erro no servidor.

Exemplos

Configurando ou Atualizando a URL de Callback

Requisição:

POST /v1.0/webhooks HTTP/1.1
Host: apps.eupreciso.com.br
Authorization: Bearer {access_token}
Content-Type: application/json
 
{
  "url": "https://integrador.com.br/webhook"
}

Resposta:

{
  "message": "URL de callback configurada com sucesso.",
  "url": "https://integrador.com.br/webhook"
}

Recuperando a URL de Callback Atual

Requisição:

GET /v1.0/webhooks HTTP/1.1
Host: apps.eupreciso.com.br
Authorization: Bearer {access_token}

Resposta:

{
  "url": "https://integrador.com.br/webhook"
}

Removendo a URL de Callback

Requisição:

DELETE /v1.0/webhooks HTTP/1.1
Host: apps.eupreciso.com.br
Authorization: Bearer {access_token}

Resposta:

{
  "message": "URL de callback removida com sucesso."
}

Observações Importantes

Segurança: Certifique-se de que sua URL de callback utiliza HTTPS para garantir a segurança dos dados transmitidos.
Validação da URL: A URL fornecida será validada. URLs inválidas ou inacessíveis podem resultar em erros.
Sobrescrita de Configuração: Utilizar o método POST sobrescreverá qualquer URL de callback configurada anteriormente.
Escopos e Tópicos: As notificações enviadas para a URL de callback respeitarão os escopos definidos na criação da aplicação.

Boas Práticas

Gestão de Tokens: Armazene e proteja adequadamente os tokens de acesso.
Respostas Rápidas: Seu endpoint de webhook deve responder rapidamente (preferencialmente em menos de 5 segundos) para evitar timeouts.
Idempotência: Certifique-se de que seu sistema pode lidar com notificações duplicadas, implementando lógica idempotente.
Logs e Monitoramento: Implemente logs para monitorar o recebimento e processamento das notificações.

Visão geral Paginação, filtros e ordenação