API atual/Referência completa/Webhooks e eventos

Catálogo de eventos

Os 21 tipos de evento que um webhook pode assinar, com o corpo real de cada um, e as rotas que listam os tipos disponíveis.

Um evento é o aviso de que algo aconteceu na loja. Ao cadastrar um webhook você escolhe a lista de tipos que quer receber (campo events). Esta página mostra o que cada tipo significa, quando é disparado e qual é o payload exato que chega à sua URL. Todos os corpos abaixo vêm das estruturas que a plataforma serializa; os valores dos exemplos são fictícios.

Lembre que o payload vem dentro do envelope {event, payload, timestamp, webhook_id}. Os campos do payload valem para os webhooks do administrador. O seller recebe os mesmos corpos, só que apenas para os tipos order.* e product.* dos próprios pedidos e produtos.

Listar os tipos assináveis

As três rotas abaixo devolvem listas de nomes de evento. Use as duas primeiras para montar uma tela de cadastro ou validar o que você vai enviar em events. A terceira serve a scripts da loja e não é a lista de webhooks.

GET/api/v1/admin/webhooks/event-typesAdmin

Tipos de evento que o administrador pode assinar, por categoria

Exige o módulo webhooks e o privilégio manage_webhooks ou manage_settings. Não tem parâmetros.

GET/api/v1/vendor/webhooks/event-typesSeller

Tipos de evento que o seller pode assinar, por categoria

Exige o módulo webhooks e um usuário seller com permissão de configurações. Não tem parâmetros. Devolve só as categorias orders e products.

GET/api/v1/admin/event-typesAdmin

Tipos de evento que um script da loja pode escutar

Exige o privilégio manage_scripts ou manage_settings. É a lista usada pelo editor de scripts da loja, e não a de webhooks: inclui order.paid e order.cancelled, e order.completed, order.shipped e os incentive.* não aparecem nela. Para webhooks, use a rota webhooks/event-types.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/webhooks/event-types" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Administrador: todas as categorias

json

{
  "incentives": [
    "incentive.campaign_published", "incentive.member_enrolled", "incentive.progress_changed",
    "incentive.award_granted", "incentive.redemption_updated", "incentive.campaign_closed",
    "incentive.resource_changed"
  ],
  "orders": ["order.created", "order.statusChanged", "order.completed", "order.cancelled", "order.shipped"],
  "products": ["product.created", "product.updated", "product.deleted"],
  "customers": ["customer.registered", "customer.updated"],
  "cart": ["cart.abandoned"],
  "reviews": ["review.created"],
  "vendors": ["vendor.registered", "vendor.approved"]
}

200Seller: somente pedidos e produtos

json

{
  "orders": ["order.created", "order.statusChanged", "order.completed", "order.cancelled", "order.shipped"],
  "products": ["product.created", "product.updated", "product.deleted"]
}

200Eventos de script

json

{
  "event_types": [
    "order.created", "order.statusChanged", "order.paid", "order.cancelled",
    "product.created", "product.updated", "product.deleted",
    "customer.registered", "customer.updated", "cart.abandoned", "review.created",
    "vendor.registered", "vendor.approved"
  ]
}

Erros

Status	Quando	Corpo
401	Token ausente ou inválido	`{"error":"invalid or expired token"}`
403	Módulo `webhooks` desligado	`{"error":"module_disabled","module":"webhooks"}`
403	Falta o privilégio `manage_webhooks` ou `manage_settings` (administrador)	`{"error":"insufficient privileges","privilege_required_any":["manage_webhooks","manage_settings"]}`
403	Falta `manage_scripts` ou `manage_settings` (rota `/admin/event-types`)	`{"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]}`
403	Usuário sem conta de seller (rota do seller)	`{"error":"no vendor account associated with this user"}`

Pedidos

order.created

Disparado depois que um pedido é gravado, seja pelo checkout, pela API ou pelo atendimento. Quando o pedido é um sub-pedido de uma compra com vários sellers, parent_order_id aponta para o pedido pai.

json

{
  "type": "order.created",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "total": 22500,
  "item_count": 3,
  "payment_method": "pix",
  "timestamp": "2026-10-11T20:15:03.482913Z"
}

Campos do payload

typestring

Sempre order.created.

order_iduuid

Id do pedido.

parent_order_iduuid

Opcional. Id do pedido pai, quando este é um sub-pedido.

customer_iduuid

Cliente que comprou.

vendor_iduuid

Seller dono do pedido. Pode vir vazio quando o pedido não pertence a um seller.

totalinteger

Total do pedido em centavos.

item_countinteger

Quantidade de itens.

payment_methodstring

Código da forma de pagamento (por exemplo pix, boleto).

timestampstring

Momento do evento, RFC 3339.

order.statusChanged

Disparado a cada mudança de status do pedido. É o evento mais útil para um ERP, porque cobre todo o ciclo. old_status e new_status são os nomes por extenso (pending, processing, shipped), e não as letras gravadas no pedido.

json

{
  "type": "order.statusChanged",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "old_status": "pending",
  "new_status": "processing",
  "changed_by": "d4613dde-ac7a-4312-9232-50d8cd6ad5fc",
  "timestamp": "2026-10-11T20:18:41.120554Z",
  "old_status_code": "pending",
  "new_status_code": "processing",
  "actor": "admin"
}

Campos do payload

typestring

Sempre order.statusChanged.

order_iduuid

Id do pedido.

old_statusstring

Status anterior, por extenso.

new_statusstring

Novo status, por extenso.

changed_bystring

Id do usuário que alterou.

timestampstring

Momento da mudança, RFC 3339.

old_status_codestring

Opcional. Código do status anterior no cadastro de status da loja.

new_status_codestring

Opcional. Código do novo status no cadastro de status da loja.

actorstring

adminvendorsystem

Opcional. Quem fez a mudança.

forcedboolean

Opcional. true quando a mudança pulou a matriz de transições permitidas.

reasonstring

Opcional. Motivo informado, obrigatório quando forced é true.

skip_customer_noticeboolean

Opcional. true quando a mudança não deve avisar o cliente dentro da loja.

order.completed

Disparado quando o pedido chega ao status concluído. Serve para programas de fidelidade e pós-venda.

json

{
  "type": "order.completed",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "total": 22500,
  "timestamp": "2026-10-18T14:02:09.771203Z"
}

Campos do payload

typestring

Sempre order.completed.

order_iduuid

Id do pedido.

customer_iduuid

Cliente do pedido.

totalinteger

Total em centavos.

timestampstring

RFC 3339.

order.cancelled

Disparado quando o pedido é cancelado. refund_amount pode ser parcial.

json

{
  "type": "order.cancelled",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "total": 22500,
  "refund_amount": 22500,
  "reason": "Pedido em duplicidade",
  "cancelled_by": "d4613dde-ac7a-4312-9232-50d8cd6ad5fc",
  "timestamp": "2026-10-12T09:30:00.004417Z"
}

Campos do payload

typestring

Sempre order.cancelled.

order_iduuid

Id do pedido.

customer_iduuid

Cliente do pedido.

totalinteger

Total original, em centavos.

refund_amountinteger

Valor devolvido, em centavos. Pode ser menor que total.

reasonstring

Motivo informado.

cancelled_bystring

Id do usuário que cancelou.

timestampstring

RFC 3339.

order.shipped

Disparado uma vez por pedido quando o status do pedido passa para enviado, mesmo que existam várias remessas. O código de rastreio não vem no evento: leia o pedido para obtê-lo (Obter pedido).

json

{
  "type": "order.shipped",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "old_status": "processing",
  "changed_by": "d4613dde-ac7a-4312-9232-50d8cd6ad5fc",
  "timestamp": "2026-10-13T11:45:30.250981Z"
}

Campos do payload

typestring

Sempre order.shipped.

order_iduuid

Id do pedido.

customer_iduuid

Cliente do pedido.

old_statusstring

Status que o pedido tinha antes de ser enviado.

changed_bystring

Id do usuário que fez a mudança.

timestampstring

RFC 3339.

Produtos

product.created

Disparado depois que um produto é gravado.

json

{
  "type": "product.created",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "name": "Camiseta Algodão Preta M",
  "category_id": "5b0d6a3e-1c44-4f6e-9c02-7f2e8d4a1b90",
  "price": 7990,
  "timestamp": "2026-10-11T19:00:12.337718Z"
}

Campos do payload

typestring

Sempre product.created.

product_iduuid

Id do produto.

vendor_iduuid

Seller dono do produto. Pode vir vazio quando o produto não pertence a um seller.

namestring

Nome do produto.

category_iduuid

Categoria principal.

priceinteger

Preço em centavos.

timestampstring

RFC 3339.

product.updated

Disparado depois que um produto é alterado. O evento traz só o id: leia o produto para ver o que mudou.

json

{
  "type": "product.updated",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "timestamp": "2026-10-11T19:12:44.901226Z"
}

Campos do payload

typestring

Sempre product.updated.

product_iduuid

Id do produto alterado.

timestampstring

RFC 3339.

product.deleted

Disparado depois que um produto é excluído (remoção lógica ou definitiva). Remova o produto do seu índice.

json

{
  "type": "product.deleted",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "timestamp": "2026-10-11T19:30:02.118840Z"
}

Campos do payload

typestring

Sempre product.deleted.

product_iduuid

Id do produto excluído.

timestampstring

RFC 3339.

Clientes, carrinho e avaliações

customer.registered

Disparado quando um novo usuário é criado. Atenção: o campo type do corpo é user.registered (nome interno do evento), enquanto o cabeçalho X-Venddor-Event e o campo event do envelope dizem customer.registered. Use sempre o event do envelope para decidir o que fazer. Para empresa (PJ), first_name traz a razão social inteira.

json

{
  "type": "user.registered",
  "user_id": "8d1e5c40-2b7a-4a39-9d6e-0f4b7c2a5e11",
  "email": "maria.souza@example.com",
  "user_type": "customer",
  "first_name": "Maria",
  "tenant_id": "store1",
  "timestamp": "2026-10-11T18:05:27.640012Z"
}

Campos do payload

typestring

user.registered.

user_iduuid

Id do usuário.

emailstring

E-mail do usuário.

user_typestring

customervendoradmin

Tipo da conta criada.

first_namestring

Opcional. Nome (ou razão social, para PJ).

person_typestring

FJ

Opcional, só para PJ. J indica pessoa jurídica.

legal_namestring

Opcional, só para PJ. Razão social.

trade_namestring

Opcional, só para PJ. Nome fantasia.

cnpjstring

Opcional, só para PJ. CNPJ.

tenant_idstring

Opcional. Identificador da loja.

timestampstring

RFC 3339.

customer.updated

Disparado quando um usuário altera o próprio perfil. O type do corpo é user.profileUpdated.

json

{
  "type": "user.profileUpdated",
  "user_id": "8d1e5c40-2b7a-4a39-9d6e-0f4b7c2a5e11",
  "email": "maria.souza@example.com",
  "fields": ["phone", "birth_date"],
  "timestamp": "2026-10-11T18:40:55.309871Z"
}

Campos do payload

typestring

user.profileUpdated.

user_iduuid

Id do usuário.

emailstring

E-mail atual.

fieldsarray

Nomes dos campos que mudaram, sem os valores.

timestampstring

RFC 3339.

cart.abandoned

Disparado quando um carrinho com itens fica parado pelo período configurado na loja. Serve para recuperação de carrinho.

json

{
  "type": "cart.abandoned",
  "cart_id": "b7e2a4c8-5d19-4e03-8c6f-91a0d3f27b44",
  "user_id": "8d1e5c40-2b7a-4a39-9d6e-0f4b7c2a5e11",
  "email": "maria.souza@example.com",
  "item_count": 2,
  "total": 15980,
  "timestamp": "2026-10-11T22:00:00.000000Z"
}

Campos do payload

typestring

Sempre cart.abandoned.

cart_iduuid

Id do carrinho.

user_iduuid

Cliente dono do carrinho.

emailstring

E-mail do cliente.

item_countinteger

Quantidade de itens.

totalinteger

Total do carrinho em centavos.

timestampstring

RFC 3339.

review.created

Disparado quando um cliente envia uma avaliação de produto. O type do corpo é review.submitted.

json

{
  "type": "review.submitted",
  "review_id": "e1f4b6d2-8a35-47c9-b0d1-3c5a9e7f2d68",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "customer_id": "8d1e5c40-2b7a-4a39-9d6e-0f4b7c2a5e11",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "rating": 5,
  "comment": "Chegou antes do prazo, tecido ótimo.",
  "timestamp": "2026-10-14T10:11:12.512340Z"
}

Campos do payload

typestring

review.submitted.

review_iduuid

Id da avaliação.

product_iduuid

Produto avaliado.

customer_iduuid

Cliente autor.

vendor_iduuid

Seller do produto.

ratinginteger

12345

Nota de 1 a 5.

commentstring

Texto da avaliação.

timestampstring

RFC 3339.

Sellers

vendor.registered

Disparado quando um seller envia o pedido de cadastro, antes da aprovação.

json

{
  "type": "vendor.registered",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "company_name": "Moda Sul Ltda",
  "cnpj": "12.345.678/0001-95",
  "timestamp": "2026-10-09T13:20:00.718455Z"
}

Campos do payload

typestring

Sempre vendor.registered.

vendor_iduuid

Id do seller.

company_namestring

Razão social informada.

cnpjstring

Opcional. CNPJ informado.

timestampstring

RFC 3339.

vendor.approved

Disparado quando um administrador aprova o cadastro do seller.

json

{
  "type": "vendor.approved",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "vendor_slug": "moda-sul",
  "company_name": "Moda Sul Ltda",
  "email": "contato@modasul.example.com",
  "approved_by": "d4613dde-ac7a-4312-9232-50d8cd6ad5fc",
  "timestamp": "2026-10-10T09:00:31.002763Z"
}

Campos do payload

typestring

Sempre vendor.approved.

vendor_iduuid

Id do seller.

vendor_slugstring

Identificador curto do seller na loja.

company_namestring

Razão social.

emailstring

E-mail do seller.

approved_bystring

Id do administrador que aprovou.

timestampstring

RFC 3339.

Incentivos

Os sete tipos incentive.* (campaign_published, member_enrolled, progress_changed, award_granted, redemption_updated, campaign_closed, resource_changed) pertencem ao módulo de campanhas de incentivo e só podem ser assinados por webhook do administrador. Eles seguem um formato diferente dos demais: são avisos "magros", que dizem o que mudou e onde ler o dado, sem copiar o conteúdo.

json

{
  "event": {
    "cursor": 1042,
    "event_id": "6c2b8f0a-91d3-4e57-a8b4-0d7e5f3a1c92",
    "event_type": "incentive.award_granted",
    "schema_version": 1,
    "campaign_id": "a1d5c7e9-3b02-4f68-9e14-8c6b0d2f4a73",
    "resource_version": 7,
    "occurred_at": "2026-10-11T20:00:00Z",
    "tenant_id": "store1",
    "resource": "/api/v1/admin/incentives/campaigns/a1d5c7e9-3b02-4f68-9e14-8c6b0d2f4a73"
  },
  "emitted_at": "2026-10-11T20:00:04.120Z",
  "timestamp": "1791748804"
}

Campos do corpo (incentivos)

event.cursorinteger

Posição do evento na fila da loja, crescente.

event.event_iduuid

Identificador único do evento. É a chave de deduplicação.

event.event_typestring

Um dos sete tipos incentive.*.

event.schema_versioninteger

Versão do formato. Hoje 1.

event.campaign_iduuid

Campanha afetada. Pode ser null.

event.resource_versioninteger

Versão do recurso depois da mudança.

event.occurred_atstring

Momento do fato, RFC 3339.

event.tenant_idstring

Loja do evento.

event.resourcestring

Caminho da API onde ler o estado atual (peça com o seu token de administrador).

emitted_atstring

Momento do envio, RFC 3339.

timestampstring

Mesmo valor do cabeçalho X-Venddor-Timestamp: segundos Unix, como texto.

As regras de entrega dos incentivos são mais estritas que as dos demais eventos:

	Eventos de incentivo	Demais eventos
Cabeçalhos	`X-Venddor-Event-ID`, `X-Venddor-Timestamp`, `X-Venddor-Signature`	`X-Venddor-Event`, `X-Venddor-Signature`
Assinatura	Mesma: `sha256=` + HMAC-SHA256 hex do corpo bruto	Idem
Sucesso	Apenas `2xx`	Qualquer status abaixo de 400
Tempo limite	3 segundos	30 segundos
Tentativas	Até 8, com espera de 30 s que dobra a cada falha (30 s, 1 min, 2 min, 4 min, 8 min, 16 min, 32 min)	Até 3 (agora, 30 s, 5 min), só para `5xx` e erro de rede
Registro	Acompanhado na área de incentivos, não aparece em `/deliveries`	Aparece em `/deliveries`

Como a entrega é "pelo menos uma vez" e um tempo limite pode esconder um envio que deu certo, deduplique por event.event_id.

Veja também

API atual/Referência completa/Webhooks e eventos

Catálogo de eventos

Os 21 tipos de evento que um webhook pode assinar, com o corpo real de cada um, e as rotas que listam os tipos disponíveis.

Listar os tipos assináveis

GET/api/v1/admin/webhooks/event-typesAdmin

Tipos de evento que o administrador pode assinar, por categoria

Exige o módulo webhooks e o privilégio manage_webhooks ou manage_settings. Não tem parâmetros.

GET/api/v1/vendor/webhooks/event-typesSeller

Tipos de evento que o seller pode assinar, por categoria

Exige o módulo webhooks e um usuário seller com permissão de configurações. Não tem parâmetros. Devolve só as categorias orders e products.

GET/api/v1/admin/event-typesAdmin

Tipos de evento que um script da loja pode escutar

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/webhooks/event-types" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Administrador: todas as categorias

json

{
  "incentives": [
    "incentive.campaign_published", "incentive.member_enrolled", "incentive.progress_changed",
    "incentive.award_granted", "incentive.redemption_updated", "incentive.campaign_closed",
    "incentive.resource_changed"
  ],
  "orders": ["order.created", "order.statusChanged", "order.completed", "order.cancelled", "order.shipped"],
  "products": ["product.created", "product.updated", "product.deleted"],
  "customers": ["customer.registered", "customer.updated"],
  "cart": ["cart.abandoned"],
  "reviews": ["review.created"],
  "vendors": ["vendor.registered", "vendor.approved"]
}

200Seller: somente pedidos e produtos

json

{
  "orders": ["order.created", "order.statusChanged", "order.completed", "order.cancelled", "order.shipped"],
  "products": ["product.created", "product.updated", "product.deleted"]
}

200Eventos de script

json

{
  "event_types": [
    "order.created", "order.statusChanged", "order.paid", "order.cancelled",
    "product.created", "product.updated", "product.deleted",
    "customer.registered", "customer.updated", "cart.abandoned", "review.created",
    "vendor.registered", "vendor.approved"
  ]
}

Erros

Status	Quando	Corpo
401	Token ausente ou inválido	`{"error":"invalid or expired token"}`
403	Módulo `webhooks` desligado	`{"error":"module_disabled","module":"webhooks"}`
403	Falta o privilégio `manage_webhooks` ou `manage_settings` (administrador)	`{"error":"insufficient privileges","privilege_required_any":["manage_webhooks","manage_settings"]}`
403	Falta `manage_scripts` ou `manage_settings` (rota `/admin/event-types`)	`{"error":"insufficient privileges","privilege_required_any":["manage_scripts","manage_settings"]}`
403	Usuário sem conta de seller (rota do seller)	`{"error":"no vendor account associated with this user"}`

Pedidos

order.created

json

{
  "type": "order.created",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "total": 22500,
  "item_count": 3,
  "payment_method": "pix",
  "timestamp": "2026-10-11T20:15:03.482913Z"
}

Campos do payload

typestring

Sempre order.created.

order_iduuid

Id do pedido.

parent_order_iduuid

Opcional. Id do pedido pai, quando este é um sub-pedido.

customer_iduuid

Cliente que comprou.

vendor_iduuid

Seller dono do pedido. Pode vir vazio quando o pedido não pertence a um seller.

totalinteger

Total do pedido em centavos.

item_countinteger

Quantidade de itens.

payment_methodstring

Código da forma de pagamento (por exemplo pix, boleto).

timestampstring

Momento do evento, RFC 3339.

order.statusChanged

json

{
  "type": "order.statusChanged",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "old_status": "pending",
  "new_status": "processing",
  "changed_by": "d4613dde-ac7a-4312-9232-50d8cd6ad5fc",
  "timestamp": "2026-10-11T20:18:41.120554Z",
  "old_status_code": "pending",
  "new_status_code": "processing",
  "actor": "admin"
}

Campos do payload

typestring

Sempre order.statusChanged.

order_iduuid

Id do pedido.

old_statusstring

Status anterior, por extenso.

new_statusstring

Novo status, por extenso.

changed_bystring

Id do usuário que alterou.

timestampstring

Momento da mudança, RFC 3339.

old_status_codestring

Opcional. Código do status anterior no cadastro de status da loja.

new_status_codestring

Opcional. Código do novo status no cadastro de status da loja.

actorstring

adminvendorsystem

Opcional. Quem fez a mudança.

forcedboolean

Opcional. true quando a mudança pulou a matriz de transições permitidas.

reasonstring

Opcional. Motivo informado, obrigatório quando forced é true.

skip_customer_noticeboolean

Opcional. true quando a mudança não deve avisar o cliente dentro da loja.

order.completed

Disparado quando o pedido chega ao status concluído. Serve para programas de fidelidade e pós-venda.

json

{
  "type": "order.completed",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "total": 22500,
  "timestamp": "2026-10-18T14:02:09.771203Z"
}

Campos do payload

typestring

Sempre order.completed.

order_iduuid

Id do pedido.

customer_iduuid

Cliente do pedido.

totalinteger

Total em centavos.

timestampstring

RFC 3339.

order.cancelled

Disparado quando o pedido é cancelado. refund_amount pode ser parcial.

json

{
  "type": "order.cancelled",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "total": 22500,
  "refund_amount": 22500,
  "reason": "Pedido em duplicidade",
  "cancelled_by": "d4613dde-ac7a-4312-9232-50d8cd6ad5fc",
  "timestamp": "2026-10-12T09:30:00.004417Z"
}

Campos do payload

typestring

Sempre order.cancelled.

order_iduuid

Id do pedido.

customer_iduuid

Cliente do pedido.

totalinteger

Total original, em centavos.

refund_amountinteger

Valor devolvido, em centavos. Pode ser menor que total.

reasonstring

Motivo informado.

cancelled_bystring

Id do usuário que cancelou.

timestampstring

RFC 3339.

order.shipped

json

{
  "type": "order.shipped",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "old_status": "processing",
  "changed_by": "d4613dde-ac7a-4312-9232-50d8cd6ad5fc",
  "timestamp": "2026-10-13T11:45:30.250981Z"
}

Campos do payload

typestring

Sempre order.shipped.

order_iduuid

Id do pedido.

customer_iduuid

Cliente do pedido.

old_statusstring

Status que o pedido tinha antes de ser enviado.

changed_bystring

Id do usuário que fez a mudança.

timestampstring

RFC 3339.

Produtos

product.created

Disparado depois que um produto é gravado.

json

{
  "type": "product.created",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "name": "Camiseta Algodão Preta M",
  "category_id": "5b0d6a3e-1c44-4f6e-9c02-7f2e8d4a1b90",
  "price": 7990,
  "timestamp": "2026-10-11T19:00:12.337718Z"
}

Campos do payload

typestring

Sempre product.created.

product_iduuid

Id do produto.

vendor_iduuid

Seller dono do produto. Pode vir vazio quando o produto não pertence a um seller.

namestring

Nome do produto.

category_iduuid

Categoria principal.

priceinteger

Preço em centavos.

timestampstring

RFC 3339.

product.updated

Disparado depois que um produto é alterado. O evento traz só o id: leia o produto para ver o que mudou.

json

{
  "type": "product.updated",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "timestamp": "2026-10-11T19:12:44.901226Z"
}

Campos do payload

typestring

Sempre product.updated.

product_iduuid

Id do produto alterado.

timestampstring

RFC 3339.

product.deleted

Disparado depois que um produto é excluído (remoção lógica ou definitiva). Remova o produto do seu índice.

json

{
  "type": "product.deleted",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "timestamp": "2026-10-11T19:30:02.118840Z"
}

Campos do payload

typestring

Sempre product.deleted.

product_iduuid

Id do produto excluído.

timestampstring

RFC 3339.

Clientes, carrinho e avaliações

customer.registered

json

{
  "type": "user.registered",
  "user_id": "8d1e5c40-2b7a-4a39-9d6e-0f4b7c2a5e11",
  "email": "maria.souza@example.com",
  "user_type": "customer",
  "first_name": "Maria",
  "tenant_id": "store1",
  "timestamp": "2026-10-11T18:05:27.640012Z"
}

Campos do payload

typestring

user.registered.

user_iduuid

Id do usuário.

emailstring

E-mail do usuário.

user_typestring

customervendoradmin

Tipo da conta criada.

first_namestring

Opcional. Nome (ou razão social, para PJ).

person_typestring

FJ

Opcional, só para PJ. J indica pessoa jurídica.

legal_namestring

Opcional, só para PJ. Razão social.

trade_namestring

Opcional, só para PJ. Nome fantasia.

cnpjstring

Opcional, só para PJ. CNPJ.

tenant_idstring

Opcional. Identificador da loja.

timestampstring

RFC 3339.

customer.updated

Disparado quando um usuário altera o próprio perfil. O type do corpo é user.profileUpdated.

json

{
  "type": "user.profileUpdated",
  "user_id": "8d1e5c40-2b7a-4a39-9d6e-0f4b7c2a5e11",
  "email": "maria.souza@example.com",
  "fields": ["phone", "birth_date"],
  "timestamp": "2026-10-11T18:40:55.309871Z"
}

Campos do payload

typestring

user.profileUpdated.

user_iduuid

Id do usuário.

emailstring

E-mail atual.

fieldsarray

Nomes dos campos que mudaram, sem os valores.

timestampstring

RFC 3339.

cart.abandoned

Disparado quando um carrinho com itens fica parado pelo período configurado na loja. Serve para recuperação de carrinho.

json

{
  "type": "cart.abandoned",
  "cart_id": "b7e2a4c8-5d19-4e03-8c6f-91a0d3f27b44",
  "user_id": "8d1e5c40-2b7a-4a39-9d6e-0f4b7c2a5e11",
  "email": "maria.souza@example.com",
  "item_count": 2,
  "total": 15980,
  "timestamp": "2026-10-11T22:00:00.000000Z"
}

Campos do payload

typestring

Sempre cart.abandoned.

cart_iduuid

Id do carrinho.

user_iduuid

Cliente dono do carrinho.

emailstring

E-mail do cliente.

item_countinteger

Quantidade de itens.

totalinteger

Total do carrinho em centavos.

timestampstring

RFC 3339.

review.created

Disparado quando um cliente envia uma avaliação de produto. O type do corpo é review.submitted.

json

{
  "type": "review.submitted",
  "review_id": "e1f4b6d2-8a35-47c9-b0d1-3c5a9e7f2d68",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "customer_id": "8d1e5c40-2b7a-4a39-9d6e-0f4b7c2a5e11",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "rating": 5,
  "comment": "Chegou antes do prazo, tecido ótimo.",
  "timestamp": "2026-10-14T10:11:12.512340Z"
}

Campos do payload

typestring

review.submitted.

review_iduuid

Id da avaliação.

product_iduuid

Produto avaliado.

customer_iduuid

Cliente autor.

vendor_iduuid

Seller do produto.

ratinginteger

12345

Nota de 1 a 5.

commentstring

Texto da avaliação.

timestampstring

RFC 3339.

Sellers

vendor.registered

Disparado quando um seller envia o pedido de cadastro, antes da aprovação.

json

{
  "type": "vendor.registered",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "company_name": "Moda Sul Ltda",
  "cnpj": "12.345.678/0001-95",
  "timestamp": "2026-10-09T13:20:00.718455Z"
}

Campos do payload

typestring

Sempre vendor.registered.

vendor_iduuid

Id do seller.

company_namestring

Razão social informada.

cnpjstring

Opcional. CNPJ informado.

timestampstring

RFC 3339.

vendor.approved

Disparado quando um administrador aprova o cadastro do seller.

json

{
  "type": "vendor.approved",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "vendor_slug": "moda-sul",
  "company_name": "Moda Sul Ltda",
  "email": "contato@modasul.example.com",
  "approved_by": "d4613dde-ac7a-4312-9232-50d8cd6ad5fc",
  "timestamp": "2026-10-10T09:00:31.002763Z"
}

Campos do payload

typestring

Sempre vendor.approved.

vendor_iduuid

Id do seller.

vendor_slugstring

Identificador curto do seller na loja.

company_namestring

Razão social.

emailstring

E-mail do seller.

approved_bystring

Id do administrador que aprovou.

timestampstring

RFC 3339.

Incentivos

json

{
  "event": {
    "cursor": 1042,
    "event_id": "6c2b8f0a-91d3-4e57-a8b4-0d7e5f3a1c92",
    "event_type": "incentive.award_granted",
    "schema_version": 1,
    "campaign_id": "a1d5c7e9-3b02-4f68-9e14-8c6b0d2f4a73",
    "resource_version": 7,
    "occurred_at": "2026-10-11T20:00:00Z",
    "tenant_id": "store1",
    "resource": "/api/v1/admin/incentives/campaigns/a1d5c7e9-3b02-4f68-9e14-8c6b0d2f4a73"
  },
  "emitted_at": "2026-10-11T20:00:04.120Z",
  "timestamp": "1791748804"
}

Campos do corpo (incentivos)

event.cursorinteger

Posição do evento na fila da loja, crescente.

event.event_iduuid

Identificador único do evento. É a chave de deduplicação.

event.event_typestring

Um dos sete tipos incentive.*.

event.schema_versioninteger

Versão do formato. Hoje 1.

event.campaign_iduuid

Campanha afetada. Pode ser null.

event.resource_versioninteger

Versão do recurso depois da mudança.

event.occurred_atstring

Momento do fato, RFC 3339.

event.tenant_idstring

Loja do evento.

event.resourcestring

Caminho da API onde ler o estado atual (peça com o seu token de administrador).

emitted_atstring

Momento do envio, RFC 3339.

timestampstring

Mesmo valor do cabeçalho X-Venddor-Timestamp: segundos Unix, como texto.

As regras de entrega dos incentivos são mais estritas que as dos demais eventos:

	Eventos de incentivo	Demais eventos
Cabeçalhos	`X-Venddor-Event-ID`, `X-Venddor-Timestamp`, `X-Venddor-Signature`	`X-Venddor-Event`, `X-Venddor-Signature`
Assinatura	Mesma: `sha256=` + HMAC-SHA256 hex do corpo bruto	Idem
Sucesso	Apenas `2xx`	Qualquer status abaixo de 400
Tempo limite	3 segundos	30 segundos
Tentativas	Até 8, com espera de 30 s que dobra a cada falha (30 s, 1 min, 2 min, 4 min, 8 min, 16 min, 32 min)	Até 3 (agora, 30 s, 5 min), só para `5xx` e erro de rede
Registro	Acompanhado na área de incentivos, não aparece em `/deliveries`	Aparece em `/deliveries`

Como a entrega é "pelo menos uma vez" e um tempo limite pode esconder um envio que deu certo, deduplique por event.event_id.