API atual/Referência completa/Webhooks e eventos

Entregas do administrador

Consulta o registro de entregas de um webhook, envia um evento de teste e reenvia uma entrega.

Toda tentativa de envio fica registrada: o que foi mandado, o status que o seu servidor respondeu, quanto demorou e o erro, se houve. Este registro é a primeira ferramenta quando algo não chega. As rotas abaixo permitem ler o registro, provocar uma chamada de teste e repetir uma entrega que falhou.

Registro de entregas

Lista as tentativas de envio de um webhook, da mais recente para a mais antiga. Se o id não existir a lista vem vazia, sem erro.

GET/api/v1/admin/webhooks/{id}/deliveriesAdmin

Registro de entregas

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

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

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/$WEBHOOK_ID/deliveries?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entregas

json

{
  "deliveries": [
    {
      "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",
        "total": 22500,
        "timestamp": "2026-10-11T20:15:03.482913Z"
      },
      "status_code": 503,
      "response_body": "Service Unavailable",
      "response_time_ms": 1204,
      "attempt": 1,
      "error": "HTTP 503",
      "delivered_at": "2026-10-11T20:15:04.700112Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Campos da resposta

iduuid

Id desta tentativa. É o deliveryId da rota de reenvio.

webhook_iduuid

Webhook ao qual a tentativa pertence.

event_typestring

Tipo do evento (por exemplo order.created), ou test no envio de teste.

payloadobject

O evento enviado (o conteúdo de payload do envelope, não o envelope inteiro).

status_codeinteger

Status HTTP respondido pelo seu servidor. null quando não houve resposta (falha de rede ou tempo esgotado).

response_bodystring

Primeiros 4096 bytes da resposta. Vazio quando não houve resposta.

response_time_msinteger

Tempo até a resposta (ou até a falha), em milissegundos.

attemptinteger

Número da tentativa: 1 a 3 no envio automático. Um reenvio manual soma 1 ao número da entrega original.

errorstring

Vazio quando deu certo. HTTP 503 para status 400 ou maior; o texto do erro de rede quando não houve resposta.

delivered_atstring

Momento da tentativa, RFC 3339.

Enviar evento de teste

Faz uma chamada real, assinada, para a URL do webhook com event: "test" e devolve o resultado na própria resposta. Funciona mesmo com o webhook pausado e não passa por novas tentativas: é uma única chamada. A tentativa fica gravada no registro.

POST/api/v1/admin/webhooks/{id}/testAdmin

Enviar evento de teste

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

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

O seu receptor recebe este corpo (o X-Venddor-Event vale test):

json

{
  "event": "test",
  "payload": {
    "test": true,
    "message": "This is a test webhook delivery from Venddor",
    "timestamp": "2026-10-11T20:20:00Z"
  },
  "timestamp": "2026-10-11T20:20:00Z",
  "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11"
}

A mensagem do teste é sempre em inglês.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Teste enviado (o servidor do cliente respondeu)

json

{
  "id": "c8e1f4a7-2d93-4b60-9a15-7e3b5d0f8c21",
  "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
  "event_type": "test",
  "payload": { "test": true, "message": "This is a test webhook delivery from Venddor", "timestamp": "2026-10-11T20:20:00Z" },
  "status_code": 200,
  "response_body": "ok",
  "response_time_ms": 142,
  "attempt": 1,
  "error": "",
  "delivered_at": "2026-10-11T20:20:00.310551Z"
}

A rota devolve 200 mesmo quando o seu servidor falha. Leia status_code e error para saber o resultado do teste: com falha de rede, status_code vem null e error traz o motivo. Os campos são os mesmos do registro de entregas.

Reenviar uma entrega

Repete o envio de uma entrega do registro, de forma síncrona, e devolve a nova tentativa. O corpo reenviado tem o mesmo event e o mesmo payload, um timestamp novo, nova assinatura e o campo extra "retry": true. Use depois de consertar o seu receptor. Não há limite de reenvios manuais, e o reenvio não dispara tentativas automáticas adicionais.

POST/api/v1/admin/webhooks/deliveries/{deliveryId}/retryAdmin

Reenviar uma entrega

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

Parâmetros de caminho

deliveryIduuidobrigatório

Id da entrega, o campo id do registro de entregas.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/webhooks/deliveries/$DELIVERY_ID/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nova tentativa registrada

json

{
  "id": "e2a9b7c4-6f10-4d85-8b3a-1c5d7e9f0a62",
  "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
  "event_type": "order.created",
  "payload": { "type": "order.created", "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b", "total": 22500 },
  "status_code": 200,
  "response_body": "ok",
  "response_time_ms": 142,
  "attempt": 2,
  "error": "",
  "delivered_at": "2026-10-11T20:20:00.310551Z"
}

Como no teste, a resposta é 200 mesmo se a nova tentativa falhar: confira status_code e error.

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 `manage_webhooks` ou `manage_settings`	`{"error":"insufficient privileges","privilege_required_any":["manage_webhooks","manage_settings"]}`
404	Teste: webhook inexistente	`{"error":"webhook not found"}`
404	Reenvio: entrega inexistente	`{"error":"delivery not found"}`
500	Falha interna	`{"error":"failed to test webhook","detail":"..."}`

Veja também

API atual/Referência completa/Webhooks e eventos

Entregas do administrador

Consulta o registro de entregas de um webhook, envia um evento de teste e reenvia uma entrega.

Registro de entregas

Lista as tentativas de envio de um webhook, da mais recente para a mais antiga. Se o id não existir a lista vem vazia, sem erro.

GET/api/v1/admin/webhooks/{id}/deliveriesAdmin

Registro de entregas

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

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

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/$WEBHOOK_ID/deliveries?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entregas

json

{
  "deliveries": [
    {
      "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",
        "total": 22500,
        "timestamp": "2026-10-11T20:15:03.482913Z"
      },
      "status_code": 503,
      "response_body": "Service Unavailable",
      "response_time_ms": 1204,
      "attempt": 1,
      "error": "HTTP 503",
      "delivered_at": "2026-10-11T20:15:04.700112Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Campos da resposta

iduuid

Id desta tentativa. É o deliveryId da rota de reenvio.

webhook_iduuid

Webhook ao qual a tentativa pertence.

event_typestring

Tipo do evento (por exemplo order.created), ou test no envio de teste.

payloadobject

O evento enviado (o conteúdo de payload do envelope, não o envelope inteiro).

status_codeinteger

Status HTTP respondido pelo seu servidor. null quando não houve resposta (falha de rede ou tempo esgotado).

response_bodystring

Primeiros 4096 bytes da resposta. Vazio quando não houve resposta.

response_time_msinteger

Tempo até a resposta (ou até a falha), em milissegundos.

attemptinteger

Número da tentativa: 1 a 3 no envio automático. Um reenvio manual soma 1 ao número da entrega original.

errorstring

Vazio quando deu certo. HTTP 503 para status 400 ou maior; o texto do erro de rede quando não houve resposta.

delivered_atstring

Momento da tentativa, RFC 3339.

Enviar evento de teste

POST/api/v1/admin/webhooks/{id}/testAdmin

Enviar evento de teste

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

Parâmetros de caminho

iduuidobrigatório

Id do webhook.

O seu receptor recebe este corpo (o X-Venddor-Event vale test):

json

{
  "event": "test",
  "payload": {
    "test": true,
    "message": "This is a test webhook delivery from Venddor",
    "timestamp": "2026-10-11T20:20:00Z"
  },
  "timestamp": "2026-10-11T20:20:00Z",
  "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11"
}

A mensagem do teste é sempre em inglês.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Teste enviado (o servidor do cliente respondeu)

json

{
  "id": "c8e1f4a7-2d93-4b60-9a15-7e3b5d0f8c21",
  "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
  "event_type": "test",
  "payload": { "test": true, "message": "This is a test webhook delivery from Venddor", "timestamp": "2026-10-11T20:20:00Z" },
  "status_code": 200,
  "response_body": "ok",
  "response_time_ms": 142,
  "attempt": 1,
  "error": "",
  "delivered_at": "2026-10-11T20:20:00.310551Z"
}

Reenviar uma entrega

POST/api/v1/admin/webhooks/deliveries/{deliveryId}/retryAdmin

Reenviar uma entrega

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

Parâmetros de caminho

deliveryIduuidobrigatório

Id da entrega, o campo id do registro de entregas.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/webhooks/deliveries/$DELIVERY_ID/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nova tentativa registrada

json

{
  "id": "e2a9b7c4-6f10-4d85-8b3a-1c5d7e9f0a62",
  "webhook_id": "0b9c2f6e-3a5d-4c0e-8a52-6a1f2f0d8c11",
  "event_type": "order.created",
  "payload": { "type": "order.created", "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b", "total": 22500 },
  "status_code": 200,
  "response_body": "ok",
  "response_time_ms": 142,
  "attempt": 2,
  "error": "",
  "delivered_at": "2026-10-11T20:20:00.310551Z"
}

Como no teste, a resposta é 200 mesmo se a nova tentativa falhar: confira status_code e error.

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 `manage_webhooks` ou `manage_settings`	`{"error":"insufficient privileges","privilege_required_any":["manage_webhooks","manage_settings"]}`
404	Teste: webhook inexistente	`{"error":"webhook not found"}`
404	Reenvio: entrega inexistente	`{"error":"delivery not found"}`
500	Falha interna	`{"error":"failed to test webhook","detail":"..."}`