API atual/Referência completa/Webhooks e eventos

Webhooks do seller

Cadastra, lista, consulta, altera e remove os webhooks de saída do próprio seller (lojista).

Um webhook cadastrado diz à Venddor para qual URL enviar quais eventos. Aqui o seller (lojista) gerencia os webhooks dos próprios pedidos e produtos: ele só recebe eventos do que lhe pertence e só pode assinar os tipos order.* e product.*. Um seller não enxerga webhooks de outro seller nem os do administrador. Leia antes o catálogo de eventos e Verificar a assinatura.

Listar webhooks

Devolve os webhooks do seller autenticado, do mais novo para o mais antigo.

GET/api/v1/vendor/webhooksSeller

Listar webhooks

Exige o módulo webhooks e um usuário seller com permissão de configurações. O seller é resolvido pelo token: você nunca envia vendor_id.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Valores acima de 100 voltam para 20.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/webhooks?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Webhooks encontrados

json

{
  "webhooks": [
    {
      "id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
      "url": "https://erp.example.com/hooks/venddor",
      "events": ["order.created", "order.statusChanged"],
      "secret": "****2d4f",
      "is_active": true,
      "description": "Sincronização com o ERP",
      "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
      "created_at": "2026-10-11T20:10:00.123456Z",
      "updated_at": "2026-10-11T20:10:00.123456Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Campos da resposta

webhooksarray

Webhooks da página, com o segredo mascarado.

totalinteger

Total de webhooks (de todas as páginas).

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página pedido.

Cadastrar webhook

Registra uma URL e a lista de eventos que ela recebe. O webhook nasce ativo e a resposta traz o secret completo, usado para verificar a assinatura. A URL é validada: precisa ser http ou https e não pode apontar para localhost, redes privadas, endereços de metadados de nuvem nem domínios .internal, .local ou .localhost.

POST/api/v1/vendor/webhooksSeller

Cadastrar webhook

Exige o módulo webhooks e um usuário seller com permissão de configurações. O seller é resolvido pelo token: você nunca envia vendor_id.

Corpo da requisição

urlstringobrigatório

URL que vai receber os eventos (POST). Obrigatória.

eventsarrayobrigatório

Lista de tipos de evento, com pelo menos um. Somente order.* e product.*: order.created, order.statusChanged, order.completed, order.cancelled, order.shipped, product.created, product.updated, product.deleted.

descriptionstring

Texto livre para você reconhecer o webhook.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.com/hooks/venddor","events":["order.created","order.statusChanged"],"description":"Sincronização com o ERP"}'

Resposta

201Webhook criado

json

{
  "id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
  "url": "https://erp.example.com/hooks/venddor",
  "events": ["order.created", "order.statusChanged"],
  "secret": "9f2c4e6a8b1d3f507a9c2e4b6d8f1a3c5e7b9d0f2a4c6e8b1d3f5a7c9e0b2d4f",
  "is_active": true,
  "description": "Sincronização com o ERP",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "created_at": "2026-10-11T20:10:00.123456Z",
  "updated_at": "2026-10-11T20:10:00.123456Z"
}

Campos da resposta

iduuid

Id do webhook. Aparece como webhook_id em cada chamada que você recebe.

urlstring

URL de destino.

eventsarray

Tipos de evento assinados.

secretstring

Segredo de assinatura (64 caracteres hexadecimais). Completo só no cadastro; mascarado (**** e 4 caracteres) nas demais respostas.

is_activeboolean

true quando o webhook está recebendo eventos.

descriptionstring

Descrição livre.

vendor_iduuid

Seller dono do webhook, definido pelo token.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

Ver um webhook

Devolve um webhook com o segredo mascarado e a última entrega registrada, útil para um indicador de saúde (verde se o status_code for 2xx).

GET/api/v1/vendor/webhooks/{id}Seller

Ver um webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Webhook e última entrega

json

{
  "webhook": {
    "id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
    "url": "https://erp.example.com/hooks/venddor",
    "events": ["order.created", "order.statusChanged"],
    "secret": "****2d4f",
    "is_active": true,
    "description": "Sincronização com o ERP",
    "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
    "created_at": "2026-10-11T20:10:00.123456Z",
    "updated_at": "2026-10-11T20:10:00.123456Z"
  },
  "latest_delivery": {
    "id": "5d7a1e93-4c2b-4f08-a6e1-9b3c0d8f2a47",
    "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
    "event_type": "order.created",
    "payload": { "type": "order.created", "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b" },
    "status_code": 200,
    "response_body": "ok",
    "response_time_ms": 184,
    "attempt": 1,
    "error": "",
    "delivered_at": "2026-10-11T20:15:03.700112Z"
  }
}

Campos da resposta

webhookobject

O webhook, com os mesmos campos do cadastro e o segredo mascarado.

latest_deliveryobject

A tentativa mais recente (veja os campos em Entregas), ou null se o webhook ainda não recebeu nada.

Alterar webhook

Altera só o que você enviar. É assim que você pausa um webhook (is_active: false), troca a URL ou muda a lista de eventos. O segredo não muda. Se events vier vazio ou ausente, a lista atual é mantida; se vier preenchida, substitui a lista inteira.

PUT/api/v1/vendor/webhooks/{id}Seller

Alterar webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Corpo da requisição

urlstring

Nova URL, validada como no cadastro.

eventsarray

Nova lista completa de eventos. Somente order.* e product.*: order.created, order.statusChanged, order.completed, order.cancelled, order.shipped, product.created, product.updated, product.deleted.

descriptionstring

Nova descrição.

is_activeboolean

false pausa o envio; true retoma. Eventos ocorridos durante a pausa não são enviados depois.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active":false}'

Resposta

200Alterado

json

{ "success": true }

Remover webhook

Remove o webhook e todo o seu registro de entregas. Não há como desfazer. Para só parar de receber, prefira is_active: false.

DELETE/api/v1/vendor/webhooks/{id}Seller

Remover webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removido

json

{ "success": true }

Erros

Status	Quando	Corpo
400	Corpo que não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	`url` ausente (cadastro)	`{"error":"url is required"}`
400	`events` vazio (cadastro)	`{"error":"at least one event is required"}`
400	Tipo de evento fora da lista permitida	`{"error":"unsupported event type: x.y"}`
400	URL recusada (esquema diferente de http/https, endereço interno ou privado, URL malformada)	`{"error":"webhook url not allowed: ssrf_forbidden: url targets internal/private/loopback address"}`
401	Token ausente ou inválido	`{"error":"invalid or expired token"}`
403	Módulo `webhooks` desligado	`{"error":"module_disabled","module":"webhooks"}`
403	Usuário sem conta de seller	`{"error":"no vendor account associated with this user"}`
404	Webhook inexistente. Um id de outro seller (ou de um webhook do administrador) também devolve 404.	`{"error":"webhook not found"}`
500	Falha interna	`{"error":"failed to create webhook","detail":"..."}` (a mensagem muda por rota)

Veja também

API atual/Referência completa/Webhooks e eventos

Webhooks do seller

Cadastra, lista, consulta, altera e remove os webhooks de saída do próprio seller (lojista).

Listar webhooks

Devolve os webhooks do seller autenticado, do mais novo para o mais antigo.

GET/api/v1/vendor/webhooksSeller

Listar webhooks

Exige o módulo webhooks e um usuário seller com permissão de configurações. O seller é resolvido pelo token: você nunca envia vendor_id.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Valores acima de 100 voltam para 20.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/webhooks?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Webhooks encontrados

json

{
  "webhooks": [
    {
      "id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
      "url": "https://erp.example.com/hooks/venddor",
      "events": ["order.created", "order.statusChanged"],
      "secret": "****2d4f",
      "is_active": true,
      "description": "Sincronização com o ERP",
      "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
      "created_at": "2026-10-11T20:10:00.123456Z",
      "updated_at": "2026-10-11T20:10:00.123456Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Campos da resposta

webhooksarray

Webhooks da página, com o segredo mascarado.

totalinteger

Total de webhooks (de todas as páginas).

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página pedido.

Cadastrar webhook

POST/api/v1/vendor/webhooksSeller

Cadastrar webhook

Exige o módulo webhooks e um usuário seller com permissão de configurações. O seller é resolvido pelo token: você nunca envia vendor_id.

Corpo da requisição

urlstringobrigatório

URL que vai receber os eventos (POST). Obrigatória.

eventsarrayobrigatório

descriptionstring

Texto livre para você reconhecer o webhook.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.com/hooks/venddor","events":["order.created","order.statusChanged"],"description":"Sincronização com o ERP"}'

Resposta

201Webhook criado

json

{
  "id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
  "url": "https://erp.example.com/hooks/venddor",
  "events": ["order.created", "order.statusChanged"],
  "secret": "9f2c4e6a8b1d3f507a9c2e4b6d8f1a3c5e7b9d0f2a4c6e8b1d3f5a7c9e0b2d4f",
  "is_active": true,
  "description": "Sincronização com o ERP",
  "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
  "created_at": "2026-10-11T20:10:00.123456Z",
  "updated_at": "2026-10-11T20:10:00.123456Z"
}

Campos da resposta

iduuid

Id do webhook. Aparece como webhook_id em cada chamada que você recebe.

urlstring

URL de destino.

eventsarray

Tipos de evento assinados.

secretstring

Segredo de assinatura (64 caracteres hexadecimais). Completo só no cadastro; mascarado (**** e 4 caracteres) nas demais respostas.

is_activeboolean

true quando o webhook está recebendo eventos.

descriptionstring

Descrição livre.

vendor_iduuid

Seller dono do webhook, definido pelo token.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

Ver um webhook

Devolve um webhook com o segredo mascarado e a última entrega registrada, útil para um indicador de saúde (verde se o status_code for 2xx).

GET/api/v1/vendor/webhooks/{id}Seller

Ver um webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Webhook e última entrega

json

{
  "webhook": {
    "id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
    "url": "https://erp.example.com/hooks/venddor",
    "events": ["order.created", "order.statusChanged"],
    "secret": "****2d4f",
    "is_active": true,
    "description": "Sincronização com o ERP",
    "vendor_id": "9a4c1d52-7e0b-4c34-b6f1-2d5e3a8c7b10",
    "created_at": "2026-10-11T20:10:00.123456Z",
    "updated_at": "2026-10-11T20:10:00.123456Z"
  },
  "latest_delivery": {
    "id": "5d7a1e93-4c2b-4f08-a6e1-9b3c0d8f2a47",
    "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
    "event_type": "order.created",
    "payload": { "type": "order.created", "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b" },
    "status_code": 200,
    "response_body": "ok",
    "response_time_ms": 184,
    "attempt": 1,
    "error": "",
    "delivered_at": "2026-10-11T20:15:03.700112Z"
  }
}

Campos da resposta

webhookobject

O webhook, com os mesmos campos do cadastro e o segredo mascarado.

latest_deliveryobject

A tentativa mais recente (veja os campos em Entregas), ou null se o webhook ainda não recebeu nada.

Alterar webhook

PUT/api/v1/vendor/webhooks/{id}Seller

Alterar webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Corpo da requisição

urlstring

Nova URL, validada como no cadastro.

eventsarray

descriptionstring

Nova descrição.

is_activeboolean

false pausa o envio; true retoma. Eventos ocorridos durante a pausa não são enviados depois.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active":false}'

Resposta

200Alterado

json

{ "success": true }

Remover webhook

Remove o webhook e todo o seu registro de entregas. Não há como desfazer. Para só parar de receber, prefira is_active: false.

DELETE/api/v1/vendor/webhooks/{id}Seller

Remover webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removido

json

{ "success": true }

Erros

Status	Quando	Corpo
400	Corpo que não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	`url` ausente (cadastro)	`{"error":"url is required"}`
400	`events` vazio (cadastro)	`{"error":"at least one event is required"}`
400	Tipo de evento fora da lista permitida	`{"error":"unsupported event type: x.y"}`
400	URL recusada (esquema diferente de http/https, endereço interno ou privado, URL malformada)	`{"error":"webhook url not allowed: ssrf_forbidden: url targets internal/private/loopback address"}`
401	Token ausente ou inválido	`{"error":"invalid or expired token"}`
403	Módulo `webhooks` desligado	`{"error":"module_disabled","module":"webhooks"}`
403	Usuário sem conta de seller	`{"error":"no vendor account associated with this user"}`
404	Webhook inexistente. Um id de outro seller (ou de um webhook do administrador) também devolve 404.	`{"error":"webhook not found"}`
500	Falha interna	`{"error":"failed to create webhook","detail":"..."}` (a mensagem muda por rota)