Como Receber Webhooks
Contexto
Um webhook é uma maneira eficiente de receber notificações e dados em tempo real de sistemas externos.
Ao configurar uma URL em seu sistema, você pode permitir que outros serviços publiquem informações para essa URL sempre que um evento relevante acontecer. Isso significa que, em vez de precisar consultar constantemente esses sistemas para obter atualizações, os dados chegam automaticamente, assim que ocorrem.
Essa abordagem é especialmente útil para automatizar processos e reagir instantaneamente a eventos importantes, como novas transações, atualizações de pedidos ou mudanças em dados, economizando tempo e recursos.
Esta documentação visa esclarecer o comportamento dos nossos webhooks, facilitando sua integração e garantindo um processo de implementação mais ágil e eficiente.
Formato Padrão das Mensagens de Webhook
As mensagens enviadas pelo webhook têm o prop ósito exclusivo de notificar sobre a ocorrência de alterações em registros, sem fornecer detalhes completos sobre a mudança em si. Esse modelo simplificado contribui para manter a comunicação via webhook segura e eficiente.
Após o recebimento de uma notificação de webhook, é comum que seu sistema realize uma consulta adicional à API para obter detalhes completos sobre o registro alterado.
Cada mensagem de webhook contém os seguintes elementos:
- status: Indica o tipo de alteração realizada no objeto, como
active,suspended, etc. - params: Um dicionário que contém os parâmetros necessários para identificar o recurso afetado.
- resource: A URI do recurso que foi alterado, que pode ser usada para consultar o dado atualizado ou criado.
- tenant_id: Identificador do cliente ao qual o evento se refere.
- topic: Define a categoria ou tipo de evento, ajudando a classificar a natureza da notificação.
Exemplo de Notificação de Promoção
{
"data": {
"status": "available",
"params": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"resource": "/seller/v1/promotions/7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"tenant_id": "3b5cf468-c858-404b-9e53-630e3df9d74a",
"topic": "promotions_promotion"
}
Exemplo de Notificação de SKU
{
"data": {
"status": "awaiting_approval",
"params": {
"promotion_id": "db8bccc7-9fb1-552b-a22d-443bdc7902b6",
"sku_id": "meu-sku-id"
},
"resource": "/seller/v1/promotions/db8bccc7-9fb1-552b-a22d-443bdc7902b6/skus/meu-sku-id"
},
"tenant_id": "3b5cf468-c858-404b-9e53-630e3df9d74a",
"topic": "promotions_sku"
}
Interpretação do Status nas Mensagens de Webhook
O campo status indica a operação realizada sobre um registro no sistema e informa ao consumidor do webhook qual ação foi tomada. Os valores e as regras de envio variam entre promoções e SKUs. Os possíveis valores são:
Promoções — promotions_promotion
Você encontra os status ao consultar GET /seller/v1/promotions/{id}.
| Status | O que significa | Você recebe uma notificação? |
|---|---|---|
available | A promoção está disponível e você pode escolher participar. | Sim |
processing | A promoção está em processamento (ex.: incluída, aguardando publicação ou remoção). | Não |
pending | Há uma alteração de edição pendente na promoção publicada. | Sim |
active | Sua participação está ativa e a promoção está publicada. | Sim |
suspended | Sua participação está suspensa temporariamente. | Sim |
error | Não foi possível publicar ou remover sua participação, ou houve erro ao editar. | Sim |
finished | Sua participação foi encerrada ou removida, ou o prazo da promoção expirou. | Sim |
O status processing aparece na consulta enquanto uma solicitação está sendo processada, mas não gera uma notificação. O motivo detalhado da situação também não é enviado no webhook. Quando precisar de mais informações, consulte a URL de resource.
SKUs — promotions_sku
Você encontra os mesmos status ao consultar GET /seller/v1/promotions/{id}/skus/{sku_id}.
| Status | O que significa | Você recebe uma notificação nesta versão? |
|---|---|---|
awaiting_approval | O Canal incluiu o SKU na promoção e aguarda sua aprovação. | Sim |
pending | Há uma solicitação de inclusão ou remoção do SKU na promoção aguardando aplicação. | Não |
processing | O SKU está aguardando publicação ou remoção, ou há uma edição pendente. | Não |
active | O SKU está publicado na promoção. | Não |
suspended | O SKU está suspenso temporariamente. | Não |
error | Não foi possível publicar ou remover o SKU, ou houve erro ao editar. | Não |
finished | O SKU foi removido da promoção. | Não |
expired | O prazo do SKU na promoção expirou. | Não |
⚠️ Se o seu sistema armazena dados das nossas APIs, é fundamental aplicar as atualizações e deleções conforme indicadas, já que podem envolver moderação e remoção de informações sensíveis de clientes.
Tópicos de Inscrição e Exemplos de Notificações
Ao se inscrever para receber notificações do nosso webhook, sua URL receberá mensagens referentes a diferentes tópicos, cada um relacionado a um recurso específico. Abaixo está a definição completa de cada tópico disponível, juntamente com seus possíveis status e um exemplo de mensagem.
| Tópico | Descrição | Status enviados | Exemplo de Mensagem |
| promotions_promotion | Mudanças importantes no status da sua participação em promoções. O status 'processing' não gera notificação. Permissão necessária: open:promotion-promotions-seller:read | available, pending, active, suspended, error, finished | |
| promotions_sku | Avisa quando o Canal inclui um SKU na promoção e precisa da sua aprovação. | awaiting_approval | |
Receba Atualizações por Webhook
Para configurar um webhook, siga a documentação do portal de desenvolvedores