Webhooks — receba os eventos de assinatura em tempo real

Formato do payload

Todas as entregas compartilham o mesmo esquema JSON de nível superior: `event`, `data` e `timestamp`. O nome do evento também é repetido no cabeçalho `X-Certyneo-Event`, o que permite rotear antes mesmo de analisar o corpo. O conteúdo de `data` varia de acordo com o evento, mas permanece sempre um objeto plano de valores simples — nunca um array ou objeto aninhado. Aqui está uma entrega `envelope.completed` completa.

POST /webhooks/certyneo HTTP/1.1
Host: your.app
Content-Type: application/json
X-Certyneo-Event: envelope.completed
X-Certyneo-Delivery-Id: cm8f2h6a10004qr9k5p2wm3xt
X-Certyneo-Signature: 4f3d1c8b2a9e7f60d5c4b3a2918e7f6d5c4b3a2918e7f6d5c4b3a2918e7f6d5c

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "sandbox": false,
    "subject": "Contrat de prestation Acme Corp",
    "status": "COMPLETED",
    "signatureLevel": "ADVANCED",
    "aesSignerCount": 2,
    "completedAt": "2026-05-27T08:42:13.000Z",
    "recipientCount": 2,
    "recipients": [
      { "email": "alice@acme.com", "name": "Alice Martin", "role": "SIGNER", "status": "SIGNED" },
      { "email": "bob@acme.com", "name": "Bob Durand", "role": "SIGNER", "status": "SIGNED" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/cm7x2k9p4.../contrat.pdf?X-Amz-Expires=604800&X-Amz-Signature=..."
  },
  "timestamp": "2026-05-27T08:42:13.521Z"
}

signedDocumentUrl é um link pré-assinado válido por 7 dias a contar do evento: evita uma segunda chamada autenticada para recuperar o PDF. Está ausente — e não nulo — se a pré-assinatura falhou, ou em um envelope QES concluído sem documento armazenado; então volte a GET /v1/envelopes/id/signed-document, que permanece a fonte de verdade. Tenha cuidado também com a reprodução manual da dead-letter queue mais de 7 dias após o evento: o link do payload está expirado, o endpoint da API não.

O payload é codificado em UTF-8, sem BOM. A assinatura HMAC é calculada sobre o body bruto tal como enviado — não altere espaços, o re-parsing JSON geralmente modifica a ordem das chaves e interrompe a verificação.

Verificar a assinatura HMAC

Cada requisição é assinada com seu segredo de webhook (exibido uma única vez na criação da inscrição). A assinatura é transmitida no cabeçalho `X-Certyneo-Signature`: é o HMAC-SHA256 do corpo bruto da requisição, codificado em hexadecimal, sem prefixo nem timestamp. SEMPRE verifique a assinatura antes de processar o payload — sem esta etapa, qualquer pessoa pode falsificar um evento e chamar seu endpoint.

import crypto from "node:crypto";

export function verifyCertyneoSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  // X-Certyneo-Signature = HMAC-SHA256(secret, rawBody), hex-encoded.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = Buffer.from(signatureHeader, "hex");
  const computed = Buffer.from(expected, "hex");

  // timingSafeEqual throws when the two buffers differ in length —
  // a malformed header must return false, not crash the handler.
  if (received.length !== computed.length) return false;

  // timingSafeEqual to mitigate timing attacks.
  return crypto.timingSafeEqual(computed, received);
}

import hashlib
import hmac


def verify_certyneo_signature(
    raw_body: bytes, signature_header: str, secret: str
) -> bool:
    """Verify a Certyneo webhook signature.

    `X-Certyneo-Signature` holds the hex-encoded HMAC-SHA256 of the
    raw request body, computed with your webhook secret.
    """
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature_header)

Política de retry

Se seu endpoint demora muito a responder, recusa a conexão ou retorna um 5xx (ou um 429), nós retentamos conforme um backoff exponencial: 5 tentativas no total, ao longo de aproximadamente 1 h 20. Passada a quinta, o evento vai para fila de mensagens não entregues — consultável e rejogável a partir de seu dashboard, mas não mais retentado automaticamente. Uma recusa explícita (401, 403, 404, 410, 422…) nunca é retentada: a resposta não mudaria, o evento vai diretamente para fila de mensagens não entregues.

Os prazos indicados são mínimos: a varredura de retentativa é cadenciada por um cron, uma tentativa pode portanto partir ligeiramente após a hora teórica. Os eventos abandonados são listados em Webhooks → Falhas, com um botão de rejogo manual e sem limite de duração de retenção. Um endpoint que encadeia cinco falhas definitivas — ou que responde 404 / 410 — é desativado automaticamente, e você é notificado por email: reative-o uma vez corrigido, o contador recomeça do zero (qualquer entrega bem-sucedida o recoloca também a zero).

Testar sem enviar um envelope verdadeiro

Primeiro crie uma inscrição — a resposta contém o `secret` necessário para a verificação HMAC, exibido uma única vez. A partir de Configurações → Webhooks, o botão « Testar » envia então um POST assinado exatamente como uma entrega real e exibe a resposta bruta do seu servidor: é a forma mais rápida de validar seu handler, localmente via ngrok ou em integração contínua.

# Create a subscription — "secret" is returned once, store it now.
curl -X POST https://api.certyneo.com/v1/webhooks \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your.app/webhooks/certyneo",
    "events": ["envelope.completed", "recipient.signed"]
  }'

A URL deve ser publicamente acessível em HTTPS: um endereço privado ou localhost é rejeitado pela proteção SSRF no momento da criação da inscrição.

As assinaturas são separadas por ambiente, assim como as chaves: um webhook criado com uma chave sk_test_ só recebe os eventos dos envelopes de teste, e um criado com uma chave sk_live_ só os dos envelopes reais. Assim, um envelope de teste nunca chega à sua URL de produção, e cada payload indica "sandbox" (true ou false).

Para saber mais

• Hub do desenvolvedor
• API de assinatura eletrônica
• Integrações nativas
• Página de segurança
• Planos e preços