Assinatura das notificações

Toda notificação enviada pela Spedy é assinada. A assinatura permite confirmar que o POST recebido partiu da Spedy e que o corpo não foi alterado no caminho — sem ela, qualquer pessoa que descubra a URL do seu endpoint consegue enviar um evento forjado. A assinatura segue o padrão aberto Standard Webhooks, o que permite usar bibliotecas prontas em vez de implementar a verificação do zero.

Verificar a assinatura é opcional. O corpo das notificações não mudou e integrações criadas antes deste recurso continuam funcionando sem alteração.

Os headers da assinatura

Cada entrega inclui três headers:

Header	Conteúdo
`webhook-id`	Identificador da entrega. É o mesmo valor do campo `id` do corpo — use-o para deduplicar.
`webhook-timestamp`	Momento do envio, em segundos desde a época Unix (UTC).
`webhook-signature`	Uma ou mais assinaturas, no formato `v1,<base64>`, separadas por espaço.

POST /webhooks/spedy HTTP/1.1
Content-Type: application/json; charset=utf-8
webhook-id: 3f2b1c9e-5a7d-4e18-9c3a-7b6f2d1e8a04
webhook-timestamp: 1754932800
webhook-signature: v1,K5oT9r8GKYqrTwjUPD8ILPZIo2LaLaSwMfKQ9r8=

O header pode trazer mais de uma assinatura durante uma janela de rotação (veja Rotacionar o segredo). Considere a entrega válida quando qualquer uma delas conferir.

Obter o segredo da conta

O segredo é da conta — o mesmo valor assina as entregas de todos os webhooks configurados, de todas as empresas.

cURL

curl https://api.spedy.com.br/v1/webhooks/secret \
  -H "X-Api-Key: sua-chave-de-api"

{
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
  "createdAt": "2026-08-21T15:11:50+00:00",
  "previousSecretExpiresAt": null
}

Campo	Descrição
`secret`	O segredo em claro, no formato `whsec_` + base64. Guarde-o como credencial.
`createdAt`	Quando o segredo atual passou a valer.
`previousSecretExpiresAt`	Até quando o segredo anterior ainda é aceito. `null` fora de uma janela de rotação.

O segredo pode ser consultado quantas vezes for necessário — não é revelado uma única vez. Se você o perdeu, consulte-o novamente; não é preciso rotacionar.

createdAt e previousSecretExpiresAt são devolvidos em UTC, com offset explícito (+00:00). Os demais campos de data da API usam o horário de São Paulo. Considere o offset ao calcular o fim de uma janela de rotação.

Como verificar

O conteúdo assinado é a concatenação do identificador da entrega, do timestamp e do corpo exatamente como recebido, separados por ponto:

{webhook-id}.{webhook-timestamp}.{corpo}

Sobre esse conteúdo aplica-se HMAC com SHA-256, usando como chave os bytes resultantes da decodificação em base64 do segredo sem o prefixo whsec_. O resultado é codificado em base64 e comparado com cada entrada v1, do header.

Use o corpo cru da requisição, byte a byte. Desserializar o JSON e serializá-lo de novo altera espaçamento e ordem de campos, e a assinatura deixa de conferir. Na maioria dos frameworks isso significa ler o corpo antes de qualquer middleware de parsing.

Com uma biblioteca

O site do Standard Webhooks mantém bibliotecas oficiais para várias linguagens. Elas recebem o segredo, os headers e o corpo cru, e cuidam da verificação e da tolerância de tempo.

Sem biblioteca

const crypto = require("crypto");

const TOLERANCIA_SEGUNDOS = 300;

function verificarAssinatura(secret, headers, corpoCru) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];

  const agora = Math.floor(Date.now() / 1000);
  if (Math.abs(agora - Number(timestamp)) > TOLERANCIA_SEGUNDOS) {
    return false;
  }

  const chave = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const conteudo = `${id}.${timestamp}.${corpoCru}`;
  const esperada = crypto.createHmac("sha256", chave).update(conteudo).digest("base64");

  return headers["webhook-signature"].split(" ").some((parte) => {
    const [versao, assinatura] = parte.split(",");
    if (versao !== "v1" || !assinatura) {
      return false;
    }
    const a = Buffer.from(assinatura);
    const b = Buffer.from(esperada);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

import base64
import hashlib
import hmac
import time

TOLERANCIA_SEGUNDOS = 300


def verificar_assinatura(secret: str, headers: dict, corpo_cru: bytes) -> bool:
    webhook_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]

    if abs(int(time.time()) - int(timestamp)) > TOLERANCIA_SEGUNDOS:
        return False

    chave = base64.b64decode(secret.removeprefix("whsec_"))
    conteudo = f"{webhook_id}.{timestamp}.".encode() + corpo_cru
    esperada = base64.b64encode(hmac.new(chave, conteudo, hashlib.sha256).digest()).decode()

    for parte in headers["webhook-signature"].split(" "):
        versao, _, assinatura = parte.partition(",")
        if versao == "v1" and hmac.compare_digest(esperada, assinatura):
            return True

    return False

<?php

const TOLERANCIA_SEGUNDOS = 300;

function verificarAssinatura(string $secret, array $headers, string $corpoCru): bool
{
    $id = $headers['webhook-id'];
    $timestamp = $headers['webhook-timestamp'];

    if (abs(time() - (int) $timestamp) > TOLERANCIA_SEGUNDOS) {
        return false;
    }

    $chave = base64_decode(substr($secret, strlen('whsec_')));
    $conteudo = "{$id}.{$timestamp}.{$corpoCru}";
    $esperada = base64_encode(hash_hmac('sha256', $conteudo, $chave, true));

    foreach (explode(' ', $headers['webhook-signature']) as $parte) {
        [$versao, $assinatura] = array_pad(explode(',', $parte, 2), 2, '');

        if ($versao === 'v1' && hash_equals($esperada, $assinatura)) {
            return true;
        }
    }

    return false;
}

Compare as assinaturas com uma função de tempo constante — timingSafeEqual em Node.js, hmac.compare_digest em Python, hash_equals em PHP. Comparação com == ou != vaza informação pelo tempo de execução.

Tolerância de tempo e retentativas

O webhook-timestamp permite rejeitar entregas antigas reenviadas por terceiros. A tolerância recomendada é de 5 minutos. Uma entrega que falha é reenviada com backoff crescente, e cada retentativa é assinada de novo, com timestamp do momento do reenvio. Uma retentativa que chega 16 horas depois passa normalmente na tolerância de 5 minutos. O webhook-id, por outro lado, permanece o mesmo em todas as tentativas — é por ele que se deduplica.

Rotacionar o segredo

Rotacione o segredo quando suspeitar de exposição ou por política interna. A troca gera um segredo novo e mantém o anterior válido por um período de transição:

cURL

curl -X POST https://api.spedy.com.br/v1/webhooks/secret/rotate \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{ "overlapHours": 24 }'

{
  "secret": "whsec_novoSegredoEmBase64AquiXYZ123",
  "previousSecretExpiresAt": "2026-08-22T15:11:50+00:00"
}

Campo	Descrição
`overlapHours`	Horas em que o segredo anterior continua sendo aceito. Aceita de `0` a `72`; quando omitido, aplica `24`. O corpo inteiro é opcional.

Durante a janela, cada entrega vai assinada com os dois segredos — o novo e o anterior — no mesmo header webhook-signature. Isso permite atualizar o segredo no seu sistema quando for conveniente, sem perder entregas. Encerrada a janela, apenas o segredo novo é usado. overlapHours: 0 invalida o segredo anterior imediatamente. Use essa opção quando o segredo tiver sido exposto e a interrupção de entregas for aceitável até você atualizar o seu lado.

Uma nova rotação dentro de uma janela ainda aberta descarta o segredo mais antigo: a cada momento valem no máximo dois segredos.

Gerenciamento de webhooks

Crie, edite, desabilite e reative webhooks via API. Política de retry.

Eventos e payload

Tipos de evento disponíveis e o formato completo do payload.

​Os headers da assinatura

​Obter o segredo da conta

​Como verificar

​Com uma biblioteca

​Sem biblioteca

​Tolerância de tempo e retentativas

​Rotacionar o segredo

Gerenciamento de webhooks

Eventos e payload

Os headers da assinatura

Obter o segredo da conta

Como verificar

Com uma biblioteca

Sem biblioteca

Tolerância de tempo e retentativas

Rotacionar o segredo