Webhook

Chave	Tipo	Descrição
code	string	ID do objeto
date	datetime	Data da última tentativa.
type	string	Tipo de evento
status	string	Presente quando o evento é `order.create` ou `order.update`. Indica o status do pedido.

Observação: o payload pode incluir campos adicionais específicos do recurso (order, customer, etc.).

Events Type

Tipo	Descrição
order.create	Acionamento sempre que um pedido é criado
order.update	Acionamento sempre que um pedido é atualizado
customer.create	Acionamento sempre que um cliente é criado
customer.update	Acionamento sempre que um cliente é atualizado

🚧
Portas padrão por protocolo (http e https)
No caso de habilitar uma porta específica para recebimento de webhooks, para cada protocolo abaixo existe uma porta específica:
http:80
https:8080

📘
Inspeção e depuração
Você pode usar o RequestBin para inspecionar e depurar facilmente os webhooks recebidos.

📘
Cadastro do Webhook no console
Para cadastrar webhook no console da loja, [clique aqui] e acesse o link do nosso tutorial

Cabeçalhos adicionados (assinatura e metadados)

Em cada request foram adicionadas as seguintes headers:

convertize-hook-signature
Assinatura HMAC do payload (string). Use para verificar autenticidade.
convertize-hook-resource
Tipo do recurso enviado (por exemplo: order, customer) — ajuda a identificar rapidamente o recurso recebido.
convertize-hook-timestamp
Timestamp associado à assinatura (inteiro em segundos desde epoch). Use para evitar replay attacks verificando a tolerância de tempo.

Assinatura HMAC

Recomendamos o uso de HMAC-SHA256 para assinar o webhook. Exemplo de esquema (recomendado):

O cabeçalho convertize-hook-timestamp contém um inteiro Unix (segundos desde epoch).
A string assinada é: ${raw_body} — ou seja, corpo bruto (raw) do request.
A assinatura é: hex(HMAC-SHA256(secret, ${raw_body}))
O resultado hex é colocado no header convertize-hook-signature.

Valide também:

Timestamp dentro de uma janela de tolerância (ex.: ±300 segundos).
Comparação de assinaturas usando comparação em tempo constante (constant-time) para evitar ataques de timing.

Boas práticas de segurança

Use HTTPS para endpoints de webhook sempre que possível.
Proteja o segredo (SECRET) e gire-o periodicamente.
Use comparação em tempo-constante (constant-time) para evitar ataques de timing.
Verifique o timestamp para evitar replay attacks (ex.: tolerância 5 minutos).
Logue apenas metadados (não armazene segredos ou payloads sensíveis sem proteção).
Responda rapidamente (200) após aceitar a mensagem; utilize filas internas para processamento demorado.