| name | tray-webhooks |
| description | Sistema de Notificação (Webhook) da Tray. Utilize quando o desenvolvedor precisar implementar notificações em tempo real para alterações em produtos, pedidos, clientes, variações e configurações da loja. Inclui todos os escopos suportados, formato de payload, lógica de retry e boas práticas de implementação.
|
| when_to_use | Use quando o desenvolvedor mencionar: webhook, notificação, evento, listener, endpoint receptor, escopo de notificação, product_stock, order_insert, payload x-www-form-urlencoded, retry de notificação ou sincronização em tempo real.
|
| when_not_to_use | Não use para notificações de pagamento — chegam via escopo order deste mesmo skill. Para ativar escopos além de order, abra chamado no suporte Tray.
|
MANDATORY: Tool Calls Required Before Answering
Estas chamadas são OBRIGATÓRIAS, não opcionais. Execute-as antes de gerar
qualquer código ou payload. Se você está respondendo sem ter chamado as duas
ferramentas abaixo, pare e chame agora.
1. Buscar documentação atualizada (sempre)
node skills/tray-dev/scripts/search_docs.mjs --topic=webhooks "<termo da pergunta>"
<TOPIC_SLUG>: ver tabela em skills/tray-dev/SKILL.md.- Use os trechos retornados como fonte primária; este SKILL.md é resumo.
2. Validar payload localmente (antes de retornar código)
node skills/webhooks/scripts/validate.mjs --schema=webhook.payload '<payload_json>'
- Schemas disponíveis:
webhook.payload. Use --list-schemas para confirmar.
- Exit codes:
0 válido · 1 inválido · 2 erro de uso.
- Para output programático:
--json.
- Corrija todos os erros antes de retornar o código (até 3 tentativas).
Antes de responder
Execute estas verificações antes de gerar qualquer payload ou código:
- Confirme o método HTTP e endpoint correto para a operação solicitada.
- Identifique os campos obrigatórios listados neste documento — não omita nenhum.
- Verifique que
access_token não aparece como literal string no código gerado.
- Confirme que esta é a skill correta para o recurso (leia
when_not_to_use no frontmatter).
Sistema de Notificação (Webhook) — API Tray
Documentação oficial: https://developers.tray.com.br/#apis-de-sistema-de-notificacao-webhook
Ativação
Os webhooks devem ser ativados via ticket de suporte da Tray, informando a URL do endpoint receptor do seu aplicativo.
Escopos Suportados
| Escopo | Ações | Descrição |
|---|
product | insert, update, delete | Criação, atualização ou exclusão de produto |
product_price | update | Alteração de preço de produto |
product_stock | update | Alteração de estoque de produto |
variant | insert, update, delete | Criação, atualização ou exclusão de variação |
variant_price | update | Alteração de preço de variação |
variant_stock | update | Alteração de estoque de variação |
order | insert, update | Criação ou atualização de pedido |
customer | insert, update, delete | Criação, atualização ou exclusão de cliente |
store_config | update | Alteração de configuração da loja (inclui ativação de MultiCD) |
Ativação de escopos: por padrão, a Tray libera apenas o escopo order. Para habilitar outros escopos, abra um chamado no suporte Tray informando a URL de notificação e os escopos desejados.
Sobre pagamentos: não existe escopo de webhook payment. Notificações de pagamento chegam via escopo order — o objeto de pedido retornado pela API contém o campo payments_notification com a URL e os dados de pagamento. Consulte o skill tray-pagamentos para detalhes.
Formato do Payload
O webhook envia um POST com Content-Type: application/x-www-form-urlencoded — sempre, incluindo os de MultiCD.
| Campo | Tipo | Descrição |
|---|
seller_id | integer | ID da loja que disparou o evento |
scope_id | integer | ID do recurso afetado (ex: ID do produto) |
scope_name | string | Nome do escopo (ex: product, order) |
act | string | Ação realizada: insert, update ou delete |
app_code | string | Código do aplicativo que recebe a notificação |
url_notification | string | URL de notificação cadastrada no aplicativo |
Exemplo de payload completo:
seller_id=391250&scope_id=4375797&scope_name=order&act=update&app_code=718&url_notification=https://suaurldenotificacao
Leitura em PHP:
$sellerID = $_POST["seller_id"];
$scopeName = $_POST["scope_name"];
$scopeID = $_POST["scope_id"];
$act = $_POST["act"];
switch ($scopeName . "_" . $act) {
case "product_insert":
case "product_update":
$productID = $scopeID;
break;
case "order_insert":
case "order_update":
$orderID = $scopeID;
break;
case "customer_delete":
$customerID = $scopeID;
break;
}
Lógica de Retry
- Se o endpoint retornar qualquer código diferente de 200, a Tray reenvia a notificação
- O reenvio segue backoff progressivo (intervalos crescentes entre tentativas)
- A Tray mantém as notificações por até 20 dias após a desinstalação do app
Webhook com MultiCD
Quando o MultiCD está ativo na loja, os webhooks de product_stock e variant_stock são disparados para alterações de estoque em qualquer centro de distribuição.
Boas Práticas
- Responda rápido — retorne HTTP 200 imediatamente, antes de processar o evento
- Processamento assíncrono — coloque o evento em uma fila e processe em background
- Idempotência — trate notificações duplicadas (o mesmo evento pode chegar mais de uma vez)
- Validação — valide o
seller_id para confirmar que o evento pertence à loja esperada
- Consulta complementar — após receber o webhook, consulte a API para obter dados atualizados do recurso
- Logs — registre todos os webhooks recebidos para debug e auditoria
Exemplo de Endpoint Receptor
Ao receber um webhook, seu endpoint deve:
- Responder HTTP 200 imediatamente
- Extrair
scope_name, scope_id e act do payload
- Se necessário, consultar a API Tray para obter dados completos
- Processar a alteração na sua aplicação
Como Usar no Claude Code
Exemplos de Prompt
- "implementa um endpoint receptor de webhooks da Tray em Node.js"
- "cria a lógica de processamento para os eventos order_insert e order_update"
- "como configuro meu app para receber notificações de estoque em tempo real?"
- "implementa tratamento de webhooks com fila assíncrona e idempotência"
O que o Claude faz
- Gera o endpoint receptor com leitura do payload
x-www-form-urlencoded
- Implementa o switch por
scope_name + "_" + act para rotear eventos
- Adiciona resposta imediata HTTP 200 + processamento assíncrono via fila
- Inclui validação do
seller_id e tratamento de duplicatas (idempotência)
O que você recebe
- Endpoint receptor com parsing correto de
application/x-www-form-urlencoded
- Switch de roteamento por evento (order_insert, product_stock, customer_update, etc.)
- Lógica de resposta rápida + processamento em background
- Handler de idempotência para evitar processamento duplicado
Pré-requisitos
- URL de endpoint publicamente acessível (HTTPS recomendado)
- Ativação do webhook via ticket de suporte Tray informando a URL
access_token configurado para chamadas complementares à API
