API atual/Referência completa/Webhooks e eventos

Webhooks do administrador

Cadastra, lista, consulta, altera e remove os webhooks de saída da loja inteira.

Um webhook cadastrado diz à Venddor para qual URL enviar quais eventos. Aqui o administrador gerencia os webhooks da loja inteira: eles recebem os eventos de todos os pedidos, produtos, clientes e sellers. Para entender o formato do que chega à sua URL, leia antes o catálogo de eventos e Verificar a assinatura.

Listar webhooks

Devolve os webhooks da loja (os cadastrados por administradores), do mais novo para o mais antigo. Webhooks de seller não aparecem aqui.

GET/api/v1/admin/webhooksAdmin

Listar webhooks

Exige o módulo webhooks e o privilégio manage_webhooks ou manage_settings.

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/admin/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",
      "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/admin/webhooksAdmin

Cadastrar webhook

Exige o módulo webhooks e o privilégio manage_webhooks ou manage_settings.

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. Qualquer tipo do catálogo.

descriptionstring

Texto livre para você reconhecer o webhook.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/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",
  "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.

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/admin/webhooks/{id}Admin

Ver um webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/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",
    "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/admin/webhooks/{id}Admin

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. Qualquer tipo do catálogo.

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/admin/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/admin/webhooks/{id}Admin

Remover webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/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"}`
500	URL recusada (esquema diferente de http/https, endereço interno ou privado, URL malformada)	`{"error":"failed to create webhook","detail":"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	Falta `manage_webhooks` ou `manage_settings`	`{"error":"insufficient privileges","privilege_required_any":["manage_webhooks","manage_settings"]}`
404	Webhook inexistente.	`{"error":"webhook not found"}`
500	Falha interna	`{"error":"failed to create webhook","detail":"..."}` (a mensagem muda por rota)

A rota do administrador devolve 500 com a causa em detail; a do seller devolve 400.

Veja também

API atual/Referência completa/Webhooks e eventos

Webhooks do administrador

Cadastra, lista, consulta, altera e remove os webhooks de saída da loja inteira.

Listar webhooks

Devolve os webhooks da loja (os cadastrados por administradores), do mais novo para o mais antigo. Webhooks de seller não aparecem aqui.

GET/api/v1/admin/webhooksAdmin

Listar webhooks

Exige o módulo webhooks e o privilégio manage_webhooks ou manage_settings.

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/admin/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",
      "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/admin/webhooksAdmin

Cadastrar webhook

Exige o módulo webhooks e o privilégio manage_webhooks ou manage_settings.

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. Qualquer tipo do catálogo.

descriptionstring

Texto livre para você reconhecer o webhook.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/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",
  "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.

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/admin/webhooks/{id}Admin

Ver um webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/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",
    "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/admin/webhooks/{id}Admin

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. Qualquer tipo do catálogo.

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/admin/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/admin/webhooks/{id}Admin

Remover webhook

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/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"}`
500	URL recusada (esquema diferente de http/https, endereço interno ou privado, URL malformada)	`{"error":"failed to create webhook","detail":"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	Falta `manage_webhooks` ou `manage_settings`	`{"error":"insufficient privileges","privilege_required_any":["manage_webhooks","manage_settings"]}`
404	Webhook inexistente.	`{"error":"webhook not found"}`
500	Falha interna	`{"error":"failed to create webhook","detail":"..."}` (a mensagem muda por rota)

A rota do administrador devolve 500 com a causa em detail; a do seller devolve 400.