Webhooks
A Docublock notifica seu sistema quando seus documentos mudam. Configure a URL e o secret pelo painel ou por API.
GET/PUT /api/webhooks/config descritos abaixo.Eventos
| Evento | Quando é disparado |
|---|---|
document.sent_for_signature | O documento foi enviado aos signatários. |
document.signed | Um signatário individual completou sua assinatura. |
document.fully_signed | Todos os signatários assinaram. |
document.cancelled | O documento foi cancelado. |
document.rejected | Um signatário recusou a assinatura. |
Payload
A Docublock faz um POST para a sua URL com este corpo:
{
"event": "document.fully_signed",
"timestamp": "2026-04-24T14:22:03Z",
"document_id": "665f1a2b3c4d5e6f7a8b9c0d",
"envelope_id": "RAD-20260424-1a2b3c4d",
"source": "nuwwe",
"contract_type": "contrato_arrendamiento",
"signer": {
"email": "maria@ejemplo.com",
"identification": "1019234567",
"cellphone": "+573001112233"
},
"signing_url": "https://app.docublock.co/validar-identidad/..."
}Os campos marcados com ? podem estar ausentes dependendo do contexto do documento. envelope_id?, contract_type?, signing_url?, signer.identification?, signer.cellphone?.
Configuração por API
/api/webhooks/configBearerRetorna a configuração de webhook atual da sua organização.
/api/webhooks/configBearerAtualiza a URL, secret e status do webhook.
Campos do corpo:
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
url | string | ✔ | URL do seu endpoint (http ou https). |
secret | string | ✔ | Secret para assinar as entregas (mínimo 16 caracteres). |
enabled | boolean | — | Ativa ou desativa o webhook (por padrão true). |
Resposta: { "configured": true }
Verificação de assinatura (HMAC)
Cada entrega inclui headers de verificação:
| Header | Descrição |
|---|---|
X-Docublock-Signature | HMAC-SHA256 do corpo, em hexadecimal, assinado com o seu secret. |
X-Docublock-Event | Nome do evento. |
Content-Type | application/json |
Recalcule o HMAC do corpo bruto com o seu secret e compare com o header (Node.js):
const crypto = require("crypto");
const expected = crypto
.createHmac("sha256", WEBHOOK_SECRET)
.update(rawBody) // cuerpo crudo, sin parsear
.digest("hex");
const valid = crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(req.headers["x-docublock-signature"]),
);Entrega e retries
Seu endpoint deve responder 2xx. Em caso de falha, a Docublock refaz o retry até 3 vezes com backoff exponencial (1s, 2s) e um timeout de 10s por tentativa. O webhook só é entregue se estiver habilitado e tiver URL e secret configurados.
