WEBHOOKS
Webhooks
Receba eventos em tempo real do Superroute — pedidos, mudanças de status, atualizações de rastreamento. Com payloads assinados, retentativas automáticas e depurador integrado.
WEBHOOKS
Receba eventos em tempo real do Superroute — pedidos, mudanças de status, atualizações de rastreamento. Com payloads assinados, retentativas automáticas e depurador integrado.
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.
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.
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.
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.
Descrição legível por máquina de todos os eventos de saída, com esquemas de payload, cabeçalhos e planos de nova tentativa (AsyncAPI 3.0): asyncapi-webhooks.json
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 PayloadDispara a cada transição de status — coletado, em trânsito, entregue, exceção, cancelado. Configure via order_status_change_webhook_url.
Exemplos de PayloadDispara 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 PayloadDispara 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 PayloadDisparado 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. Quando um funcionário substitui uma fotografia ou assinatura, ou define uma versão arquivada como atual, o ficheiro é enviado com action: updated e contém apenas a imagem atual; as versões arquivadas nunca são enviadas.
Exemplos de PayloadDisparado quando um pedido é excluído permanentemente, para que seu sistema possa espelhar a remoção. Ativado configurando order_deleted_webhook_url.
Exemplos de PayloadDisparado 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 PayloadDisparado 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 PayloadUm 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.
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 PayloadEntregue 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 PayloadRecolhido — Disparado quando o destinatário retirou os pacotes depositados.
Exemplos de PayloadFalha na entrega — Disparado quando uma entrega falha; códigos de falha por pacote são incluídos.
Exemplos de PayloadExpirado — Disparado quando um código de entrega não utilizado ou um depósito não retirado ultrapassa o prazo de validade.
Exemplos de PayloadCancelado — Disparado quando uma entrega é cancelada antes da conclusão.
Exemplos de PayloadReabertura 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 PayloadCódigo de levantamento alterado — 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 PayloadPacote da transportadora distribuído — Dispara quando um pacote pré-avisado da transportadora recebido num armazém é colocado numa ordem de distribuição para o local indicado pela transportadora. O bloco data traz o número do pacote, a referência da transportadora e o número de membro, a ordem de distribuição (order_id, order_ref, status) e os locais de origem e destino. Registado apenas para transportadoras com conta de fornecedor.
Exemplos de PayloadPacote da transportadora carregado — Dispara quando o pacote é lido para o camião no armazém de origem; distribution.status é in_transit e loaded_at está preenchido.
Exemplos de PayloadPacote da transportadora entregue no local — Dispara quando o motorista entrega a ordem de distribuição no local; distribution.status é delivered e delivered_at está preenchido. O armazenamento é um evento posterior e separado.
Exemplos de PayloadPacote da transportadora armazenado no local — Dispara quando o pacote é armazenado no local, num compartimento de cacifo ou numa prateleira; location traz grid_id, grid_code e shelf_code. A notificação de levantamento ao destinatário sai nesse momento.
Exemplos de PayloadPacote da transportadora removido da distribuição — Dispara quando o pacote é retirado de uma ordem de distribuição antes da partida, ou a ordem é cancelada; distribution.reason é removed ou cancelled. O pacote volta à lista de distribuição do armazém.
Exemplos de PayloadAssinatura 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.
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.
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 PayloadPacotes Entregues em Mãos — Disparado quando o armazém entregou fisicamente todos os pacotes da atribuição ao fornecedor.
Exemplos de PayloadAtribuiçã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 PayloadEntrega 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 PayloadAssinatura 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.
Pushes assinados sobre entregas trocadas pelo Open Order Handoff Protocol: mudanças de ciclo de vida (aceita, rejeitada, expirada, cancelada), respostas a alterações, eventos de rastreamento e novas linhas de liquidação. Assinado por token OHP via POST /api/v1/ohp/subscriptions; o endpoint deve devolver um desafio antes de a assinatura existir. Cada carga é o envelope OHP; message_id permanece igual em cada nova tentativa — deduplique por ele. O pull continua sendo a fonte da verdade.
Assinatura e Verificação: X-Ohp-Signature: v1= + HMAC-SHA256 hexadecimal de "{timestamp}.{raw body}" com o segredo da assinatura. X-Ohp-Timestamp muda por tentativa; X-Ohp-Delivery é igual a message_id. CloudEvents e Standard Webhooks estão disponíveis por assinatura.
Como Configurar: Gerenciado com o token OHP: POST /api/v1/ohp/subscriptions (url, secret, events, format, signature), GET para listar, DELETE para revogar. O catálogo legível por máquina lista cada evento sob o remetente ohp.
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.
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 PayloadO pedido perdeu o seu motorista (transferência, revogação, recusa, tempo esgotado). data.previous_driver_id indica quem o tinha.
Exemplos de PayloadO motorista aceitou na app um pedido atribuído automaticamente (turno de motoristas com aceitação obrigatória).
Exemplos de PayloadO motorista recusou um pedido atribuído; data.reason contém o motivo opcional em texto livre.
Exemplos de PayloadO motorista iniciou a recolha (estado Coleta iniciada / Saiu para coleta).
Exemplos de PayloadA encomenda foi recolhida (estado Já coletado).
Exemplos de PayloadA encomenda está a caminho do destinatário (estado Entrega iniciada / Saiu para entrega).
Exemplos de PayloadA entrega foi bem-sucedida (estado Bem-sucedido).
Exemplos de PayloadA tentativa de entrega falhou (Reentregar mais tarde, Precisa reagendar, Rejeitado pelo destinatário).
Exemplos de PayloadO pedido foi cancelado.
Exemplos de PayloadA equipa (ou um motorista, quando permitido) marcou o pedido como pronto para recolha (Opções de despacho → pronto para recolha).
Exemplos de PayloadUm motorista entrou ou saiu de turno na app (opção de turno de motoristas).
Exemplos de PayloadUma 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 PayloadComo 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 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.
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 PayloadA 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 PayloadO pessoal retirou a encomenda da máquina. removal_reason indica o motivo: overdue_return, handover, relay, anomaly ou recovery.
Exemplos de PayloadA 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 PayloadFoi 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 PayloadUma pessoa fechou um problema sobre o tratamento. data.exception.status é resolved ou dismissed e resolution_action indica o que foi feito.
Exemplos de PayloadExemplos 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.
Você pode configurar webhooks em dois níveis: empresa (cobre tudo) ou por cliente (sobrescreve para aquela subconta B2B específica).
Faça login e vá em Configurações → API e Webhooks. As sobrescritas por cliente ficam na página de detalhes do cliente.
Escolha uma string de pelo menos 16 caracteres, idealmente 32+ bytes aleatórios. O receptor usará para verificar as assinaturas.
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. Quando um funcionário substitui uma fotografia ou assinatura, ou define uma versão arquivada como atual, o ficheiro é enviado com action: updated e contém apenas a imagem atual; as versões arquivadas nunca são enviadas.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.Tudo o que há de novo na API e nos webhooks — cancelamento idempotente, feeds de conciliação, assinaturas v2, novos eventos — com exemplos prontos para copiar. Tudo totalmente retrocompatível.
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.
Cada URL de webhook pode receber eventos no formato nativo ou como CloudEvents, e pode também receber cabeçalhos de assinatura Standard Webhooks. Define-se por URL nas definições de webhook. Uma URL sem definição recebe os eventos exatamente como antes.
native — O corpo JSON e os cabeçalhos descritos nesta página.ce_binary — O mesmo corpo; os atributos CloudEvents são enviados como cabeçalhos ce-*.ce_structured — O corpo é um CloudEvent (Content-Type: application/cloudevents+json) com o corpo nativo em data. É idêntico em cada nova tentativa e as assinaturas nativas cobrem-no.ce-id e webhook-id contêm o event_id próprio do evento quando o corpo tem um; caso contrário, X-Webhook-Event-Id. X-Webhook-Event-Id não muda. ce-source e ce-srbusiness indicam a empresa, também nos envios aos seus clientes.
Os webhooks de entregas em cacifos de parceiros e de entrega de terceiros oferecem a mesma opção por endpoint, na página de definições de webhook do fornecedor. Os callbacks de planos de carga e da Open Platform recebem-na por pedido: callback_format e callback_signature, ou callback.format e callback.signature. Neles, ce-id e webhook-id são o identificador próprio do evento (X-Webhook-Id, X-Webhook-Event-Id ou X-Open-Delivery), ce-source indica a empresa que envia e, durante 24 horas após uma rotação de chave do fornecedor, webhook-signature contém uma assinatura por chave.
Os webhooks de conjuntos de dados oferecem a mesma opção por webhook, no formulário do webhook e na sua API (event_format e standard_signature). Standard Webhooks usa a chave secreta do webhook, pelo que precisa de uma. Os URL dos webhooks de conjuntos de dados têm de ser endereços HTTPS públicos.
Com Standard Webhooks, cada envio inclui também webhook-id, webhook-timestamp e webhook-signature. São assinados de novo em cada nova tentativa, pelo que uma nova tentativa fica dentro de uma tolerância de 5 minutos. A chave é a sua chave de assinatura de webhook no formato whsec_, mostrada na página de definições. Os cabeçalhos nativos continuam a ser enviados.
Cada remetente assina de forma diferente. O nome de cabeçalho X-Webhook-Signature é usado por três remetentes com três métodos diferentes; verifique com o método do remetente que o chamou.
| Remetente | Cabeçalhos | Assinatura |
|---|---|---|
| Webhooks de cliente (esta página) | Content-Type, Signature, X-Webhook-Event-Id, X-Webhook-Timestamp, X-Webhook-Signature-V2 |
Signature = hex(HMAC-SHA256(body))
X-Webhook-Signature-V2 = hex(HMAC-SHA256(timestamp + "." + body)) |
| Entregas em cacifos de parceiros | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature, X-Webhook-Test |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Atribuições a entrega de terceiros | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Callbacks de planos de carga | Content-Type, X-Webhook-Event-Id, X-Webhook-Event-Type, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| Callbacks de tarefas da Open Platform | Content-Type, X-Open-Event, X-Open-Delivery, X-Open-Job, X-Open-Timestamp, X-Open-Signature |
X-Open-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| OHP push | Content-Type, X-Ohp-Event, X-Ohp-Delivery, X-Ohp-Timestamp, X-Ohp-Signature |
|
| Webhooks de conjuntos de dados | Content-Type, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = hex(HMAC-SHA256(body)) |
| Webhooks de cliente com Standard Webhooks | webhook-id, webhook-timestamp, webhook-signature |
webhook-signature = "v1," + base64(HMAC-SHA256(webhook-id + "." + webhook-timestamp + "." + body)) |
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.
Seu endpoint deve responder rapidamente com 2xx. Caso contrário, em timeout ou inacessibilidade, a entrega é retentada.
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.
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.
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.
Os registos de entrega são mantidos durante 90 dias.
Um reenvio manual recebe um novo X-Webhook-Event-Id. Um event_id transportado pelo próprio evento (pod.files_updated, order.deleted, eventos de ciclo de vida e de encomendas de dispositivo) mantém o valor original.
| Tempo | Evento | URL | Estado | HTTP | Tentativa | Tempo (ms) | Teste? | Ações |
|---|---|---|---|---|---|---|---|---|
| Ainda não há entregas de webhook. | ||||||||