Webhooks em Tempo Real & Verificação HMAC-SHA256

Visão Geral da Arquitetura

Os webhooks do CertOps notificam seus sistemas em tempo real sobre mudanças no estado dos certificados, tais como avisos de expiração (janela de 30d, 15d, 7d e 3d), sucesso na renovação atômica ou falhas em testes de sintaxe de servidores web. Cada requisição é assinada criptograficamente com HMAC-SHA256 para garantir autenticidade e imunidade contra ataques de repetição (replay attacks).

Headers de Assinatura & Entrega

Header	Descrição
`X-CertOps-Signature`	Assinatura hexadecimal HMAC-SHA256 calculada sobre o timestamp concatenado com o body JSON bruto.
`X-CertOps-Timestamp`	Timestamp UNIX em segundos do momento do disparo (tolerância máxima aceitável: 300 segundos).
`X-CertOps-Event`	Identificador do tipo de evento emitido (ex: certificate.renewed, certificate.expiring_soon).
`X-CertOps-Delivery-Id`	UUID único do evento para implementação de deduplicação e idempotência no receptor.

Catálogo de Eventos Notificáveis

certificate.expiring_soon

Disparado quando a validade atinge limiares críticos configurados no tenant (30d, 15d, 7d, 3d, 1d).

certificate.renewed

Disparado após emissão ACME, validação de sintaxe e reload bem-sucedido do servidor de aplicação.

renewal.failed

Alerta de falha em desafio ACME ou rejeição de sintaxe (com rollback preventivo acionado).

endpoint.drift_detected

Detectada divergência de certificado entre o inventário gerenciado e o endpoint de produção.

Lógica de Verificação da Assinatura

Para validar a assinatura: concatene o timestamp e o body bruto no formato '${timestamp}.${rawBody}'. Calcule o HMAC-SHA256 utilizando seu webhook secret compartilhado. Compare a assinatura resultante com o header X-CertOps-Signature utilizando comparação segura em tempo constante (timing-safe).

Exemplos de Implementação

python

import hmac
import hashlib

def verify_webhook(raw_payload: bytes, signature: str, timestamp: str, secret: str) -> bool:
    signed_payload = f"{timestamp}.".encode('utf-8') + raw_payload
    expected = hmac.new(secret.encode('utf-8'), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

nodejs

import crypto from 'node:crypto';

function verifyWebhook(rawPayload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${rawPayload}`;
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

go

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

func VerifyWebhook(rawPayload []byte, signature, timestamp, secret string) bool {
	h := hmac.New(sha256.New, []byte(secret))
	h.Write([]byte(fmt.Sprintf("%s.", timestamp)))
	h.Write(rawPayload)
	expected := hex.EncodeToString(h.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(signature))
}

Pronto para automatizar a infraestrutura TLS da sua organização?

Crie sua conta corporativa ou conecte seu primeiro agente Linux para inventário contínuo.

Acessar Console Privado Scanner TLS Gratuito