Guia de Integração de Webhook

O que são webhooks?

Um webhook é uma requisição HTTP POST que o Superroute envia para uma URL que você configura sempre que algo acontece — um pedido é criado, uma entrega é concluída, um evento de rastreamento é registrado. Você cria um endpoint receptor, nós entregamos o evento.

Como funciona a entrega

Os eventos são enfileirados e enviados de forma assíncrona. Cada requisição traz uma assinatura HMAC-SHA256 para verificação. Entregas falhas (não 2xx ou timeout) são retentadas com backoff exponencial até 5 vezes.

Modelo de segurança

Você configura um segredo compartilhado na página de configurações. Cada webhook de saída é assinado com esse segredo. Seu receptor recalcula a assinatura e compara — se coincidirem, o payload é autêntico e não foi adulterado.

Catálogo de Eventos

Oito tipos de eventos de saída disponíveis. Cada um tem seu próprio campo URL na página de configurações — assine qualquer subconjunto.

pedido.criado

Dispara ao criar um pedido de entrega local (Delivery / Pickup / P2P) por qualquer caminho: formulário web, API REST/GraphQL, sincronização com plataforma de e-commerce, regras automáticas, linhas importadas, etc. Exclui pedidos label-service e outros tipos que não são de entrega. Ignorado no fluxo em lote quando o mesmo destinatário também tem order_create_async_postback_url configurado. Configure via order_create_webhook_url.

Exemplos de Payload

pedido.status_change

Dispara a cada transição de status — coletado, em trânsito, entregue, exceção, cancelado. Configure via order_status_change_webhook_url.

Exemplos de Payload

rastreamento.evento

Dispara a cada evento do ciclo de vida do rastreamento (informações enviadas, início da entrega, entrega bem-sucedida, não entregue, etc.). Configure via tracking_event_webhook_url. Os eventos de entrega e de coleta também trazem o comprovante de entrega: proof_files e proof_files_detail (file_id, type, url, full_url, URL de download assinada). Fotos enviadas após o evento chegam como pod.files_updated. Cada arquivo também traz o contexto do seu evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); em arquivos antigos sem evento registrado são null.

Exemplos de Payload

{
    "id": 90001,
    "order_id": 1001,
    "order_ref": "REF-001",
    "location_id": 12,
    "location_name": "Toronto Depot",
    "tracking_event_type": "D",
    "tracking_event_status_id": 500,
    "tracking_event_key": "deliver_success",
    "otep_status": "delivered",
    "proof_files": [
        "storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
        "storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg"
    ],
    "proof_files_detail": [
        {
            "file_id": 234567,
            "type": 1,
            "url": "storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
            "full_url": "https://api.superroute.ca/storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
            "signed_url": "https://api.superroute.ca/files/pod/234567?expires=1784748600&signature=8f2c1d...",
            "signed_url_expires_at": 1784748600,
            "tracking_event_id": 90001,
            "tracking_event_status_id": 500,
            "tracking_event_key": "deliver_success",
            "service_type": 1,
            "service_status": 1
        },
        {
            "file_id": 234568,
            "type": 2,
            "url": "storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg",
            "full_url": "https://api.superroute.ca/storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg",
            "signed_url": "https://api.superroute.ca/files/pod/234568?expires=1784748600&signature=41ba90...",
            "signed_url_expires_at": 1784748600,
            "tracking_event_id": 90001,
            "tracking_event_status_id": 500,
            "tracking_event_key": "deliver_success",
            "service_type": 1,
            "service_status": 1
        }
    ],
    "description": {
        "en": "Your parcel has been delivered successfully. Thank you!",
        "fr": "Votre colis a été livré avec succès. Merci !",
        "chs": "您的包裹已成功送达，感谢您的使用！",
        "cht": "您的包裹已成功送達，感謝您的使用！",
        "es": "Tu paquete ha sido entregado con éxito. ¡Gracias!",
        "de": "Ihr Paket wurde erfolgreich zugestellt. Vielen Dank!",
        "nl": "Uw pakket is succesvol afgeleverd, bedankt voor uw gebruik!",
        "pt": "Seu pacote foi entregue com sucesso. Obrigado!",
        "it": "Il tuo pacco è stato consegnato con successo. Grazie!",
        "sr": "Vaš paket je uspešno dostavljen, hvala vam što koristite naše usluge!",
        "hu": "Csomagja sikeresen kiszállításra került, köszönjük hogy használta szolgáltatásunkat!",
        "pl": "Twoja paczka została dostarczona pomyślnie. Dziękujemy!",
        "sk": "Váš balík bol úspešne doručený. Ďakujeme!",
        "cs": "Váš balík byl úspěšně doručen. Děkujeme!"
    },
    "tracking_number": [
        "SR000000001"
    ],
    "external_tracking_number": [
        "1Z999AA10123456784"
    ]
}

pedido.create_async

Dispara uma vez após o processamento de uma importação em lote. O payload contém o array de resultados por linha. Configure via order_create_async_postback_url.

Exemplos de Payload

Arquivos POD atualizados

Disparado quando uma foto de entrega ou assinatura é adicionada, substituída ou removida (action: added / updated / removed) — um envio por arquivo, sem mais polling de anexos. Ativado configurando pod_files_webhook_url. Cada arquivo também traz o contexto do seu evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); em arquivos antigos sem evento registrado são null.

Exemplos de Payload

Pedido excluído

Disparado quando um pedido é excluído permanentemente, para que seu sistema possa espelhar a remoção. Ativado configurando order_deleted_webhook_url.

Exemplos de Payload

Falha no cancelamento do pedido

Disparado quando uma tentativa de cancelamento é rejeitada (por exemplo, o pedido já está em rota de entrega), para que sua operação possa monitorar cancelamentos com falha sem consultar a API. Ativado configurando order_cancel_failed_webhook_url.

Exemplos de Payload

Lugar do quadro de rotas alterado

Disparado quando um lugar do quadro de rotas muda de titular ou o quadro muda de estado — o campo action indica o que aconteceu (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Apenas ao nível da empresa. Assinatura via route_board_webhook_url.

Exemplos de Payload

Eventos de armários de fornecedors

Um canal de webhooks separado para fornecedors de entrega terceirizados integrados a armários inteligentes. Os eventos são entregues ao endpoint configurado para sua conta de fornecedor, e cada endpoint pode assinar qualquer subconjunto de tipos de evento.

partner_locker.delivery.doors_opened

Portas Abertas — Dispara no momento em que as portas dos cacifos se abrem para uma tentativa de entrega — quer o estafeta tenha usado o ecrã do cacifo com o código de acesso quer a API de abertura remota — incluindo reaberturas por reatribuição. O bloco opening lista cada compartimento aberto com o grid_id, o número de porta de hardware compartment_number e o pickup_locker_number (número sequencial de exibição contado de cima para baixo por coluna e depois da esquerda para a direita). Cada compartimento traz ainda pickup_locker_code — a etiqueta "{shelf_code}-{pickup_locker_number}" para onde o destinatário é encaminhado; null quando o compartimento não tem número de recolha. O payload inclui também pickup_code — o código de recolha do destinatário, atribuído no momento em que as portas se abrem; permanece o mesmo código depois de o estafeta confirmar o depósito e só passa a poder ser usado para recolha após essa confirmação.

Exemplos de Payload

partner_locker.delivery.delivered

Entregue no cacifo — Disparado quando um depósito é confirmado e os pacotes estão no armário. O payload inclui o código de retirada do destinatário. Cada compartimento traz ainda pickup_locker_code — a etiqueta "{shelf_code}-{pickup_locker_number}" para onde o destinatário é encaminhado; null quando o compartimento não tem número de recolha. Para portas abertas através da API de abertura remota, a plataforma liquida o depósito assim que o armário comunica que todas as portas abertas foram fechadas, pelo que este evento dispara sem chamada a confirm; confirmed_by indica a via de liquidação: courier_terminal, partner_api, door_close, timeout_door_closed ou console.

Exemplos de Payload

partner_locker.pickup.completed

Recolhido — Disparado quando o destinatário retirou os pacotes depositados.

Exemplos de Payload

partner_locker.delivery.failed

Falha na entrega — Disparado quando uma entrega falha; códigos de falha por pacote são incluídos.

Exemplos de Payload

partner_locker.delivery.expired

Expirado — Disparado quando um código de entrega não utilizado ou um depósito não retirado ultrapassa o prazo de validade.

Exemplos de Payload

partner_locker.delivery.cancelled

Cancelado — Disparado quando uma entrega é cancelada antes da conclusão.

Exemplos de Payload

partner_locker.delivery.correction_reopened

Reabertura de correção — Disparado quando os compartimentos ocupados são reabertos dentro da janela de correção para corrigir uma colocação errada — pela tela do armário ou via API. O bloco correction lista os compartimentos reabertos. Cada compartimento traz ainda pickup_locker_code — a etiqueta "{shelf_code}-{pickup_locker_number}" para onde o destinatário é encaminhado; null quando o compartimento não tem número de recolha.

Exemplos de Payload

partner_locker.delivery.code_rotated

partner_locker_delivery.event_type_code_rotated — Dispara quando o parceiro renova o código de entrega ou o código de recolha de uma entrega. O bloco rotation indica que código foi substituído, quando e se a notificação ao destinatário foi reenviada — o novo código nunca viaja num webhook; é revelado apenas na resposta direta da API de renovação.

Exemplos de Payload

Assinatura e Verificação: Os webhooks de armários de fornecedors usam um esquema de assinatura próprio: X-Webhook-Signature é base64(HMAC-SHA256(segredo, carimbo de tempo + "\n" + id da entrega + "\n" + corpo bruto)), onde o carimbo de tempo e o id da entrega vêm dos cabeçalhos X-Webhook-Timestamp e X-Webhook-Delivery-Id. Verifique também X-Webhook-Content-Digest (SHA-256 do corpo) e rejeite carimbos de tempo obsoletos. X-Webhook-Id permanece estável entre novas tentativas — use-o para idempotência.

Como Configurar: Os endpoints são gerenciados em Entrega de terceiros → Armário de fornecedors → Configurações, um endpoint por fornecedor, com uma lista de eventos selecionável. Entregas com falha são repetidas com backoff exponencial até 7 vezes antes de irem para a dead letter; eventos em dead letter podem ser reenviados manualmente pela página de eventos.

Eventos de sandbox (cacifos simulados): As entregas criadas em cacifos simulados emitem os mesmos eventos de webhook que a produção, assinados com o mesmo segredo, para que possa desenvolver com tráfego realista. Os eventos de sandbox são marcados de três formas: o payload contém "livemode": false, o event_id começa por PLE-MOCK- e o pedido inclui o cabeçalho X-Webhook-Test: 1. Se o endpoint tiver um URL de sandbox configurado, os eventos de sandbox são enviados para lá em vez do URL de produção; caso contrário recorrem ao URL de produção, sempre marcados. O interruptor «Entregar eventos de sandbox» interrompe totalmente a entrega de sandbox.

Eventos de Entrega de Terceiros

Webhooks de entrega de pacotes enviados aos fornecedores de entrega terceirizados (transportadoras). Cobrem o ciclo de vida das atribuições de entrega, para que a transportadora não precise mais consultar novos trabalhos por polling. Esta categoria é separada dos eventos de Smart Locker abaixo: cada fornecedor configura um endpoint, segredo de assinatura e subscrição de eventos independentes por categoria — no seu próprio portal ou pelo operador da plataforma.

delivery.assignment.created

Atribuição Criada — Disparado quando um pedido é atribuído ao fornecedor — por regra automática ou manualmente. O payload contém o número da atribuição, os identificadores do pedido e os números de rastreamento dos pacotes.

Exemplos de Payload

delivery.assignment.handed_over

Pacotes Entregues em Mãos — Disparado quando o armazém entregou fisicamente todos os pacotes da atribuição ao fornecedor.

Exemplos de Payload

delivery.assignment.cancelled

Atribuição Cancelada — Disparado quando a plataforma retira uma atribuição do fornecedor. O campo reason distingue cancelled (a atribuição foi cancelada na transportadora), fallback_to_self_delivery (a plataforma retomou o pedido para entrega própria) e reassigned (o pedido foi movido para outro fornecedor).

Exemplos de Payload

delivery.assignment.partial_delivered

Entrega parcial — É acionado quando parte de um envio foi entregue enquanto outros volumes continuam em curso. O array packages traz o resultado de cada volume e legs lista as encomendas externas registadas na transportadora — uma por volume quando a transportadora não aceita envios com vários volumes.

Exemplos de Payload

Assinatura e Verificação: Os webhooks de entrega de terceiros usam o mesmo esquema de assinatura dos webhooks de armário de fornecedors: X-Webhook-Signature é base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), com o timestamp e o delivery id retirados dos cabeçalhos X-Webhook-Timestamp e X-Webhook-Delivery-Id. Verifique também X-Webhook-Content-Digest (SHA-256 do corpo) e rejeite timestamps antigos. X-Webhook-Id permanece estável entre novas tentativas — use-o para idempotência.

Como Configurar: Os fornecedores configuram este endpoint por conta própria no portal do fornecedor (Configurações de Webhook), ou o operador da plataforma o faz em Entrega de terceiros → Fornecedores → Webhooks. Um endpoint por fornecedor com lista de eventos selecionável. O segredo de assinatura pode ser gerado automaticamente ou definido com um valor personalizado, e pode ser consultado na página de configurações. Entregas com falha são repetidas com backoff exponencial até 7 vezes antes de irem para a dead letter; eventos em dead letter podem ser reenviados manualmente. Um evento de teste (mock) assinado pode ser enviado a qualquer momento pela página de configurações — as requisições de teste levam o cabeçalho X-Webhook-Test: 1 e contêm "test": true nos dados do payload.

Eventos do Ciclo de Vida do Pedido

Eventos detalhados e opcionais ao lado do webhook clássico order.status_change (que se mantém inalterado): quem foi atribuído, se o motorista aceitou, quando a encomenda foi recolhida, está a caminho, foi entregue ou falhou, além das mudanças de turno dos motoristas e das posições dos motoristas com frequência limitada. Nada é enviado até configurar os URLs abaixo.

order.assigned

Um motorista foi atribuído ao pedido (manualmente, pelo planeamento de rotas ou pela atribuição automática). data.source = auto_assign quando foi o orquestrador a fazê-lo.

Exemplos de Payload

order.unassigned

O pedido perdeu o seu motorista (transferência, revogação, recusa, tempo esgotado). data.previous_driver_id indica quem o tinha.

Exemplos de Payload

order.accepted

O motorista aceitou na app um pedido atribuído automaticamente (turno de motoristas com aceitação obrigatória).

Exemplos de Payload

order.rejected

O motorista recusou um pedido atribuído; data.reason contém o motivo opcional em texto livre.

Exemplos de Payload

order.pickup_started

O motorista iniciou a recolha (estado Coleta iniciada / Saiu para coleta).

Exemplos de Payload

order.picked_up

A encomenda foi recolhida (estado Já coletado).

Exemplos de Payload

order.on_the_way

A encomenda está a caminho do destinatário (estado Entrega iniciada / Saiu para entrega).

Exemplos de Payload

order.completed

A entrega foi bem-sucedida (estado Bem-sucedido).

Exemplos de Payload

order.failed

A tentativa de entrega falhou (Reentregar mais tarde, Precisa reagendar, Rejeitado pelo destinatário).

Exemplos de Payload

order.cancelled

O pedido foi cancelado.

Exemplos de Payload

order.ready

A equipa (ou um motorista, quando permitido) marcou o pedido como pronto para recolha (Opções de despacho → pronto para recolha).

Exemplos de Payload

driver.on_duty_changed

Um motorista entrou ou saiu de turno na app (opção de turno de motoristas).

Exemplos de Payload

driver.location_update

Uma posição do motorista vinda da app ou do rastreador, limitada por motorista através de driver_location_min_interval_sec (60 s por defeito). Enviada apenas para driver_location_webhook_url.

Exemplos de Payload

Como Configurar: Configurações → Webhooks (ou GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): order_lifecycle_webhook_url recebe todos os eventos order.* e driver.on_duty_changed; order_lifecycle_events restringe-os a uma lista separada por vírgulas; driver_location_webhook_url e driver_location_min_interval_sec controlam driver.location_update. Podem ser indicados vários URLs separados por vírgulas. As entregas aparecem no registo de entregas de webhooks com reference_type order / driver.

Assinatura e Verificação: Assinado exatamente como qualquer outro webhook de saída da sua conta: cabeçalho Signature legado mais X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 com o seu webhook_sign_secret. As novas tentativas reutilizam o mesmo event_id — use-o para desduplicar.

Eventos de encomendas em dispositivos

Eventos opcionais para as encomendas tratadas pelos seus cacifos inteligentes, quiosques e caixas de depósito inteligentes: uma encomenda guardada numa máquina, levantada, retirada pelo pessoal ou fora do prazo de levantamento, e os problemas abertos ou resolvidos sobre ela. Apenas aditivo — nenhum webhook existente muda e nada é enviado até configurar device_order_webhook_url.

device_order.stored

Uma encomenda foi colocada na máquina e aguarda a pessoa seguinte (destinatário, estafeta ou operador, ver data.device_order.next_actor). due_at é o prazo de levantamento.

Exemplos de Payload

device_order.collected

A encomenda foi retirada pela pessoa que esperava — o destinatário, o estafeta ou o pessoal que esvazia uma caixa de depósito inteligente.

Exemplos de Payload

device_order.removed

O pessoal retirou a encomenda da máquina. removal_reason indica o motivo: overdue_return, handover, relay, anomaly ou recovery.

Exemplos de Payload

device_order.overdue

A encomenda ultrapassou o seu due_at sem ser levantada. Continua na máquina e o código continua a funcionar; overdue_at é preenchido e next_actor passa a operator.

Exemplos de Payload

device_order.exception_opened

Foi aberto um problema sobre o tratamento (por exemplo door_left_open, deposit_unverified, item_missing, overdue). data.exception contém id, type, severity e status.

Exemplos de Payload

device_order.exception_resolved

Uma pessoa fechou um problema sobre o tratamento. data.exception.status é resolved ou dismissed e resolution_action indica o que foi feito.

Exemplos de Payload

Exemplos de Payload: data.device_order: id, kind, status, next_actor, device_type, device_id, device_name, grid_code, reference_number, order_id, external_order_id, due_at, overdue_at, stored_at, ended_at, removal_reason (horas em ISO 8601, null enquanto não ocorrerem). Os eventos de problema acrescentam data.exception: id, type, severity, status, resolution_action. O código de levantamento nunca é incluído. event_id é DOE-<id do evento do registo> e mantém-se nas novas tentativas.

Como Configurar: Definições → Webhooks (ou GET/PUT /api/v1/webhook-settings): device_order_webhook_url recebe todos os eventos device_order.*; device_order_events limita-os a uma lista separada por vírgulas. Vários URLs podem ser separados por vírgulas. As entregas aparecem no registo de entregas de webhooks com reference_type device_order.

Assinatura e Verificação: Assinado exatamente como qualquer outro webhook de saída da sua conta: cabeçalho Signature legado mais X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 com o seu webhook_sign_secret. As novas tentativas reutilizam o mesmo event_id — use-o para desduplicar.

As encomendas que uma transportadora parceira entrega nos seus cacifos com a sua própria conta não são enviadas por este canal; o parceiro recebe-as através dos seus webhooks de cacifos do fornecedor.

Como Configurar

Você pode configurar webhooks em dois níveis: empresa (cobre tudo) ou por cliente (sobrescreve para aquela subconta B2B específica).

1. Acesse as configurações

Faça login e vá em Configurações → API e Webhooks. As sobrescritas por cliente ficam na página de detalhes do cliente.

2. Defina o segredo de assinatura

Escolha uma string de pelo menos 16 caracteres, idealmente 32+ bytes aleatórios. O receptor usará para verificar as assinaturas.

3. Defina as URLs de eventos desejadas

Preencha apenas as URLs dos eventos que lhe interessam. Deixe as demais em branco.

webhook_sign_secretVocê configura um segredo compartilhado na página de configurações. Cada webhook de saída é assinado com esse segredo. Seu receptor recalcula a assinatura e compara — se coincidirem, o payload é autêntico e não foi adulterado.

order_create_webhook_urlDispara ao criar um pedido de entrega local (Delivery / Pickup / P2P) por qualquer caminho: formulário web, API REST/GraphQL, sincronização com plataforma de e-commerce, regras automáticas, linhas importadas, etc. Exclui pedidos label-service e outros tipos que não são de entrega. Ignorado no fluxo em lote quando o mesmo destinatário também tem order_create_async_postback_url configurado. Configure via order_create_webhook_url.

pedido_status_change_webhook_urlDispara a cada transição de status — coletado, em trânsito, entregue, exceção, cancelado. Configure via order_status_change_webhook_url.

rastreamento_evento_webhook_urlDispara a cada evento do ciclo de vida do rastreamento (informações enviadas, início da entrega, entrega bem-sucedida, não entregue, etc.). Configure via tracking_event_webhook_url. Os eventos de entrega e de coleta também trazem o comprovante de entrega: proof_files e proof_files_detail (file_id, type, url, full_url, URL de download assinada). Fotos enviadas após o evento chegam como pod.files_updated. Cada arquivo também traz o contexto do seu evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); em arquivos antigos sem evento registrado são null.

order_create_async_postback_urlDispara uma vez após o processamento de uma importação em lote. O payload contém o array de resultados por linha. Configure via order_create_async_postback_url.

pod_files_webhook_urlDisparado quando uma foto de entrega ou assinatura é adicionada, substituída ou removida (action: added / updated / removed) — um envio por arquivo, sem mais polling de anexos. Ativado configurando pod_files_webhook_url. Cada arquivo também traz o contexto do seu evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); em arquivos antigos sem evento registrado são null.

order_deleted_webhook_urlDisparado quando um pedido é excluído permanentemente, para que seu sistema possa espelhar a remoção. Ativado configurando order_deleted_webhook_url.

order_cancel_failed_webhook_urlDisparado quando uma tentativa de cancelamento é rejeitada (por exemplo, o pedido já está em rota de entrega), para que sua operação possa monitorar cancelamentos com falha sem consultar a API. Ativado configurando order_cancel_failed_webhook_url.

route_board_webhook_urlDisparado quando um lugar do quadro de rotas muda de titular ou o quadro muda de estado — o campo action indica o que aconteceu (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Apenas ao nível da empresa. Assinatura via route_board_webhook_url.

device_order_webhook_urlEventos opcionais para as encomendas tratadas pelos seus cacifos inteligentes, quiosques e caixas de depósito inteligentes: uma encomenda guardada numa máquina, levantada, retirada pelo pessoal ou fora do prazo de levantamento, e os problemas abertos ou resolvidos sobre ela. Apenas aditivo — nenhum webhook existente muda e nada é enviado até configurar device_order_webhook_url.

Assinatura e Verificação

Cada webhook de saída traz uma assinatura HMAC-SHA256 codificada em hexadecimal no header. Seu receptor deve recalcular a assinatura sobre o corpo bruto usando o segredo compartilhado e rejeitar a requisição se não coincidir.

Algoritmo

HMAC-SHA256 (hex)

Nome do header

Signature

Passos de verificação

Leia o corpo bruto antes que parsing ou middleware o modifiquem.
Calcule hash_hmac('sha256', rawBody, sharedSecret) e codifique em hexadecimal.
Compare com o header Signature em tempo constante (hash_equals em PHP, crypto.timingSafeEqual em Node).
Responda 2xx apenas se as assinaturas coincidirem. Caso contrário 401.

<?php
$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $rawBody, $sharedSecret);
if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Bad signature');
}
$payload = json_decode($rawBody, true);
// ... handle event ...
http_response_code(200);
echo 'ok';

const crypto = require('crypto');
const express = require('express');
const app = express();

app.use('/webhooks/superroute', express.raw({ type: 'application/json' }), (req, res) => {
    const received = req.header('Signature') || '';
    const expected = crypto.createHmac('sha256', sharedSecret)
        .update(req.body).digest('hex');
    if (!crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
        return res.status(401).send('Bad signature');
    }
    const payload = JSON.parse(req.body.toString());
    // ... handle event ...
    res.status(200).send('ok');
});

import hmac, hashlib
from flask import Flask, request, abort
app = Flask(__name__)

@app.route('/webhooks/superroute', methods=['POST'])
def webhook():
    received = request.headers.get('Signature', '')
    expected = hmac.new(shared_secret.encode(), request.data, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(received, expected):
        abort(401)
    payload = request.get_json()
    # ... handle event ...
    return 'ok', 200

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    received := r.Header.Get("Signature")
    mac := hmac.New(sha256.New, []byte(sharedSecret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    if !hmac.Equal([]byte(received), []byte(expected)) {
        w.WriteHeader(401); return
    }
    // ... handle event ...
    w.WriteHeader(200)
    w.Write([]byte("ok"))
}

require 'openssl'
require 'rack/utils'

post '/webhooks/superroute' do
  raw = request.body.read
  received = request.env['HTTP_SIGNATURE'] || ''
  expected = OpenSSL::HMAC.hexdigest('sha256', shared_secret, raw)
  halt 401 unless Rack::Utils.secure_compare(received, expected)
  payload = JSON.parse(raw)
  # ... handle event ...
  status 200
  'ok'
end

Ocultação de preços

O seu prestador de serviços pode ocultar os seus preços a uma conta de cliente, por família de pedido (Entrega Local, Serviço de etiquetas, Serviço de Envio, Serviço LTL, Serviços de Armazenamento, Serviços de mudança, pedidos de dispositivo). Quando isso se aplica a si, as entregas ao seu endpoint não trazem campos de preço: shipping_price, price_details, currency, impostos, valores de sobretaxas, preços de tarifas e semelhantes são omitidos em vez de enviados como zero. As listas de tarifas mantêm rate_id e os nomes de serviço para que ainda possa escolher um.

Retentativas e Confiabilidade

Seu endpoint deve responder rapidamente com 2xx. Caso contrário, em timeout ou inacessibilidade, a entrega é retentada.

Tentativas máximas

5 (inicial + 4 retentativas)

Timeout por tentativa

3 segundos

Recuo

Exponencial — aproximadamente 10s, 100s, 1000s, 10000s

Verificador de Assinatura

Cole um payload recebido junto com o valor do header Signature e seu segredo — a ferramenta recalcula a assinatura no navegador (nada sai desta página) e informa se coincidem.

Corpo bruto da requisição (JSON)

Seu segredo de assinatura

Valor do header Signature (a string hexadecimal enviada)

Assinatura calculada

Enviar Webhook de Teste

Dispare um webhook real e devidamente assinado a partir do nosso servidor para uma URL que você fornece. Útil para testar acessibilidade do receptor, parsing do payload e lógica de verificação de assinatura.

URL do receptor

Segredo de assinatura

Tipo de evento

Payload (opcional — deixe em branco para uma amostra padrão)

Status HTTP / Tempo de Resposta

Assinatura enviada

Corpo da Resposta

Entregas Recentes de Webhook

Veja as tentativas de entrega de webhook mais recentes na sua conta — eventos reais de produção e testes enviados desta página. Cole seu Bearer token para carregar.

Bearer Token

Tipo de evento

Estado

Tempo	Evento	URL	Estado	HTTP	Tentativa	Tempo (ms)	Teste?	Ações
Ainda não há entregas de webhook.

Boas Práticas

Confirme rápido (HTTP 200) e processe de forma assíncrona para ficar abaixo do timeout de 3 segundos.
Verifique sempre a assinatura antes de confiar no payload.
Trate eventos como at-least-once — deduplique pelo número do pedido/rastreamento.
Use endpoints HTTPS com certificado válido.
Registre as requisições recebidas para poder repeti-las se o handler tiver um bug.