DOCS
InícioPara fornecedores logísticos Webhooks

Escutar eventos com webhooks

Receba notificações de eventos em tempo real para a sua integração Zonos.

Os webhooks permitem à Zonos notificar proativamente os seus sistemas externos sempre que determinados eventos ocorrem. Quando ocorre o evento subscrito, a Zonos envia um pedido HTTP POST para o URL do webhook que especificar. O corpo do pedido contém os detalhes do evento, permitindo que o seu sistema processe o evento de forma programática.

Os webhooks são úteis para integrar a Zonos com outras plataformas, acionar fluxos de trabalho automatizados e manter os dados sincronizados entre sistemas em tempo real. Por exemplo, pode utilizar webhooks para:

  • Atualizar o seu sistema de gestão de encomendas quando é criada uma encomenda na Zonos
  • Notificar o seu prestador de serviços de logística quando um envio é cancelado
  • Registar alterações de estado de encomendas internacionais para fins de auditoria

Tipos de webhook 

Todos os tipos de webhook disponíveis estão incluídos no enum WebhookType. Pode encontrar exemplos de payloads para cada um no nosso guia Tipos de eventos.

Criar webhooks 

Para criar um webhook através da API:

1mutation WebhookCreate($input: WebhookCreateInput!) {
2 webhookCreate(input: $input) {
3 id
4 url
5 type
6 status
7 secret
8 headers {
9 key
10 }
11 }
12}

Importante: Guarde o valor de secret ao criar o webhook — só é devolvido neste momento e vai precisar dele para verificar as assinaturas dos webhooks. Consulte Verificar assinaturas de webhook abaixo.

Editar os detalhes do webhook 

Para editar um webhook existente através da API:

1mutation WebhookUpdate($input: WebhookUpdateInput!) {
2 webhookUpdate(input: $input) {
3 id
4 url
5 type
6 status
7 }
8}

Verificar assinaturas de webhook 

Todos os pedidos de webhook enviados pela Zonos incluem um cabeçalho zonos-signature, para que possa confirmar que o pedido foi realmente enviado pela Zonos e que o payload não foi alterado durante o trânsito.

O valor do cabeçalho tem o seguinte formato:

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — o momento, em milissegundos desde a época Unix, em que o pedido foi assinado.
  • hmac — uma assinatura HMAC-SHA256 do corpo JSON em bruto do pedido, calculada com o segredo do seu webhook como chave e codificada em Base64.

Para verificar um pedido:

  1. Extraia os valores de timestamp e hmac do cabeçalho zonos-signature.
  2. Calcule a sua própria assinatura HMAC-SHA256 sobre o corpo do pedido em bruto, sem processamento, utilizando o segredo que recebeu ao criar o webhook.
  3. Compare a assinatura calculada com o valor de hmac através de uma comparação em tempo constante e rejeite o pedido se não coincidirem.
  4. Opcionalmente, rejeite pedidos cujo timestamp tenha mais de alguns minutos, para se proteger contra a reutilização (replay) de um pedido intercetado. A Zonos não impõe uma janela de entrega, pelo que esta verificação fica ao seu critério.
1const crypto = require('crypto');
2 
3function verifyZonosWebhook(rawBody, signatureHeader, secret) {
4 const [timestampPart, hmacPart] = signatureHeader.split(',');
5 const receivedHmac = hmacPart.split('=')[1];
6 
7 const expectedHmac = crypto
8 .createHmac('sha256', secret)
9 .update(rawBody)
10 .digest('base64');
11 
12 const receivedBuffer = Buffer.from(receivedHmac);
13 const expectedBuffer = Buffer.from(expectedHmac);
14 
15 if (receivedBuffer.length !== expectedBuffer.length) {
16 return false;
17 }
18 
19 return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
20}

Nota: Se configurou cabeçalhos personalizados no seu webhook, estes também são incluídos tal como estão em todos os pedidos, juntamente com zonos-signature.

Ver os registos de webhook 

Para ver os registos de webhook através da API:

1query WebhookLogs(
2$first: Int
3$after: String
4$filter: WebhookLogsFilterInput
5) {
6 webhookLogs(first: $first, after: $after, filter: $filter) {
7 edges {
8 node {
9 id
10 type
11 url
12 createdAt
13 responseStatus
14 }
15 }
16 }
17}
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

WebhookCreateInput WebhookLogsFilterInput WebhookUpdateInput

MUTATIONS

webhookCreate webhookUpdate

Esta página foi útil?

Obter apoio·Documentos legais·© 2026 Zonos
Nesta página:
  • Escutar eventos com webhooks
  • Tipos de webhook
  • Criar webhooks
  • Editar os detalhes do webhook
  • Verificar assinaturas de webhook
  • Ver os registos de webhook