Receba notificações de eventos em tempo real para sua integração Zonos.
Os webhooks oferecem uma forma de a Zonos notificar proativamente seus sistemas externos sempre que determinados eventos ocorrem. Quando o evento inscrito ocorre, a Zonos envia uma solicitação HTTP POST para a URL do webhook que você especificar. O corpo da solicitação conterá os detalhes do evento, permitindo que seu sistema trate o evento de forma programática.
Os webhooks são úteis para integrar a Zonos a outras plataformas, acionar fluxos de trabalho automatizados e manter os dados sincronizados entre sistemas em tempo real. Por exemplo, você pode usar webhooks para:
Atualizar seu sistema de gerenciamento de pedidos quando um pedido for criado na Zonos
Notificar seu provedor de atendimento quando uma remessa for cancelada
Registrar alterações de status de pedidos internacionais para fins de auditoria
Todos os tipos de webhook disponíveis estão incluídos no enum WebhookType. Exemplos de payloads para cada um podem ser encontrados em nosso guia Tipos de eventos.
Importante: Salve o valor de secret ao criar o webhook — ele é retornado apenas neste momento, e você precisará dele para verificar as assinaturas dos webhooks. Consulte Verificando assinaturas de webhook abaixo.
Toda solicitação de webhook enviada pela Zonos inclui um cabeçalho zonos-signature, para que você possa confirmar que a solicitação realmente veio da Zonos e que o payload não foi alterado durante o trânsito.
timestamp — o horário, em milissegundos desde a época Unix, em que a solicitação foi assinada.
hmac — uma assinatura HMAC-SHA256 do corpo bruto da solicitação JSON, calculada usando o secret do seu webhook como chave e codificada em Base64.
Para verificar uma solicitação:
Extraia os valores de timestamp e hmac do cabeçalho zonos-signature.
Calcule sua própria assinatura HMAC-SHA256 sobre o corpo bruto e não processado da solicitação, usando o secret que você recebeu ao criar o webhook.
Compare sua assinatura calculada com o valor de hmac usando uma comparação de tempo constante e rejeite a solicitação se não corresponderem.
Opcionalmente, rejeite solicitações em que o timestamp seja anterior a alguns minutos, para se proteger contra a repetição (replay) de uma solicitação capturada. A Zonos não impõe uma janela de entrega por conta própria, portanto essa verificação fica a seu critério.
Observação: Se você configurou cabeçalhos personalizados no seu webhook, eles também são incluídos literalmente em todas as solicitações, junto com zonos-signature.
Webhooks
Ouça eventos com webhooks
Receba notificações de eventos em tempo real para sua integração Zonos.
Os webhooks oferecem uma forma de a Zonos notificar proativamente seus sistemas externos sempre que determinados eventos ocorrem. Quando o evento inscrito ocorre, a Zonos envia uma solicitação HTTP POST para a URL do webhook que você especificar. O corpo da solicitação conterá os detalhes do evento, permitindo que seu sistema trate o evento de forma programática.
Os webhooks são úteis para integrar a Zonos a outras plataformas, acionar fluxos de trabalho automatizados e manter os dados sincronizados entre sistemas em tempo real. Por exemplo, você pode usar webhooks para:
Tipos de webhook
Todos os tipos de webhook disponíveis estão incluídos no enum
WebhookType. Exemplos de payloads para cada um podem ser encontrados em nosso guia Tipos de eventos.Criando webhooks
Para criar um webhook por meio da API:
mutation WebhookCreate($input: WebhookCreateInput!) {webhookCreate(input: $input) {idurltypestatussecretheaders {key}}}Editar detalhes do webhook
Para editar um webhook existente por meio da API:
mutation WebhookUpdate($input: WebhookUpdateInput!) {webhookUpdate(input: $input) {idurltypestatus}}Verificando assinaturas de webhook
Toda solicitação de webhook enviada pela Zonos inclui um cabeçalho
zonos-signature, para que você possa confirmar que a solicitação realmente veio da Zonos e que o payload não foi alterado durante o trânsito.O valor do cabeçalho tem o seguinte formato:
timestamp— o horário, em milissegundos desde a época Unix, em que a solicitação foi assinada.hmac— uma assinatura HMAC-SHA256 do corpo bruto da solicitação JSON, calculada usando o secret do seu webhook como chave e codificada em Base64.Para verificar uma solicitação:
timestampehmacdo cabeçalhozonos-signature.hmacusando uma comparação de tempo constante e rejeite a solicitação se não corresponderem.timestampseja anterior a alguns minutos, para se proteger contra a repetição (replay) de uma solicitação capturada. A Zonos não impõe uma janela de entrega por conta própria, portanto essa verificação fica a seu critério.const crypto = require('crypto');function verifyZonosWebhook(rawBody, signatureHeader, secret) {const [timestampPart, hmacPart] = signatureHeader.split(',');const receivedHmac = hmacPart.split('=')[1];const expectedHmac = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');const receivedBuffer = Buffer.from(receivedHmac);const expectedBuffer = Buffer.from(expectedHmac);if (receivedBuffer.length !== expectedBuffer.length) {return false;}return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);}Ver registros de webhook
Para visualizar os registros de webhook por meio da API:
query WebhookLogs($first: Int$after: String$filter: WebhookLogsFilterInput) {webhookLogs(first: $first, after: $after, filter: $filter) {edges {node {idtypeurlcreatedAtresponseStatus}}}}WebhookCreateInput WebhookLogsFilterInput WebhookUpdateInput
webhookCreate webhookUpdate
Esta página foi útil?