Webhooks
Docublock notifica a tu sistema cuando cambian tus documentos. Configura la URL y el secreto desde el panel o por API.
GET/PUT /api/webhooks/config descritos abajo.Eventos
| Evento | Cuándo se dispara |
|---|---|
document.sent_for_signature | El documento se envió a los firmantes. |
document.signed | Un firmante individual completó su firma. |
document.fully_signed | Todos los firmantes firmaron. |
document.cancelled | El documento fue cancelado. |
document.rejected | Un firmante rechazó la firma. |
Payload
Docublock hace un POST a tu URL con este cuerpo:
{
"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/..."
}Los campos marcados con ? pueden estar ausentes según el contexto del documento. envelope_id?, contract_type?, signing_url?, signer.identification?, signer.cellphone?.
Configuración por API
/api/webhooks/configBearerDevuelve la configuración de webhook actual de tu organización.
/api/webhooks/configBearerActualiza la URL, secreto y estado del webhook.
Campos del cuerpo:
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
url | string | ✔ | URL de tu endpoint (http o https). |
secret | string | ✔ | Secreto para firmar las entregas (mínimo 16 caracteres). |
enabled | boolean | — | Activa o desactiva el webhook (por defecto true). |
Respuesta: { "configured": true }
Verificación de firma (HMAC)
Cada entrega incluye encabezados de verificación:
| Header | Descripción |
|---|---|
X-Docublock-Signature | HMAC-SHA256 del cuerpo, en hexadecimal, firmado con tu secreto. |
X-Docublock-Event | Nombre del evento. |
Content-Type | application/json |
Recalcula el HMAC del cuerpo crudo con tu secreto y compáralo con el 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 y reintentos
Tu endpoint debe responder 2xx. Si falla, Docublock reintenta hasta 3 veces con backoff exponencial (1s, 2s) y un timeout de 10s por intento. El webhook solo se entrega si está habilitado y tiene URL y secreto configurados.
