Skip to content

Webhooks

Cómo Sovra te avisa cuando algo termina: configurar un endpoint, validar la firma y qué evento llega en cada caso.

Un webhook es un POST que Sovra le hace a tu servidor cuando algo termina. Muchas operaciones no se resuelven en la respuesta HTTP: un holder canjea una oferta minutos después, una revocación tarda en llegar a la cadena, una wallet presenta cuando el ciudadano escanea el QR. Tu llamada devuelve un QR o un acuse; el resultado llega por webhook.

Podés consultar el GET correspondiente, pero el webhook es el único aviso que Sovra te manda solo. Funciona igual para SD-JWT VC, mDoc y documentos firmados.

Endpoints y suscripciones

  1. Creá el endpoint

    En el dashboard, andá a Settings → Workspaces → (tu workspace) → Webhooks (hace falta ser administrador del workspace). Cargá la URL de tu servidor: tiene que ser accesible desde internet. No hay endpoints de API para esto; se maneja solo desde el dashboard.

  2. Elegí los eventos

    Marcá los eventos que te interesan. No hay comodín: un endpoint recibe solo lo que tiene marcado, y un evento nuevo del catálogo no te llega hasta que lo sumes.

  3. Guardá el secreto

    Al crear el endpoint ves su secreto (whsec_…) una sola vez. Guardalo: lo necesitás para validar la firma.

Podés tener hasta 10 endpoints por workspace, cada uno con sus eventos y su propio secreto.

Más sobre endpoints: límites, rotación del secreto, varios workspaces
  • La URL tiene que cumplir ^https?:// y medir como máximo 2048 caracteres.
  • Cada endpoint tiene un flag enabled.
  • Rotar el secreto lo reemplaza de inmediato, incluso para las entregas que están esperando un reintento. El secreto nuevo también se muestra una sola vez.
  • Si varios workspaces apuntan al mismo endpoint, usá el workspace_id del payload para elegir con qué secreto validar.

Validar la firma HMAC

Verificá la firma en cada entrega. Sin eso, cualquiera que conozca tu URL puede inventarte una emisión o una verificación aprobada.

Cada entrega trae la cabecera x-sovra-signature: sha256=<hex>. Es un HMAC-SHA256 del cuerpo crudo de la petición, con el secreto completo del endpoint como clave (prefijo whsec_ incluido), en hexadecimal minúscula. Calculalo vos y comparalo en tiempo constante:

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.SOVRA_WEBHOOK_SECRET; // el whsec_… completo

// express.raw() preserva el cuerpo intacto. express.json() NO sirve acá.
app.post("/webhooks/sovra", express.raw({ type: "application/json" }), (req, res) => {
  const recibida = req.get("x-sovra-signature") ?? "";
  const esperada =
    "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");

  const a = Buffer.from(recibida);
  const b = Buffer.from(esperada);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const payload = JSON.parse(req.body.toString("utf8"));
  manejarEvento(payload).catch(console.error); // procesá en segundo plano
  res.sendStatus(200);                          // respondé rápido
});

El error más común: firmar el cuerpo después de parsearlo. JSON.parse + JSON.stringify reordena claves y cambia el espaciado, y la firma deja de coincidir.

El mismo ejemplo en Python (FastAPI)
import hmac, hashlib, os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = os.environ["SOVRA_WEBHOOK_SECRET"].encode()  # el whsec_… completo

@app.post("/webhooks/sovra")
async def sovra_webhook(request: Request):
    crudo = await request.body()
    esperada = "sha256=" + hmac.new(SECRET, crudo, hashlib.sha256).hexdigest()
    recibida = request.headers.get("x-sovra-signature", "")

    if not hmac.compare_digest(esperada, recibida):
        raise HTTPException(status_code=401, detail="firma inválida")

    payload = await request.json()
    await manejar_evento(payload)
    return {"ok": True}
Cabeceras y protección contra reinyección
POST /tu-endpoint HTTP/1.1
content-type: application/json
x-sovra-event: document.status-changed
x-sovra-signature: sha256=6f1d0c…<64 caracteres hex>

{"data":{…},"event":"document.status-changed","id":"…","timestamp":"…","workspace_id":"…"}
Header Descripción
x-sovra-event El tipo de evento, también presente en el cuerpo. Sirve para rutear sin parsear.
x-sovra-signature sha256= + HMAC-SHA256 del cuerpo crudo, en hexadecimal minúscula.

Los nombres de cabecera son insensibles a mayúsculas: tu framework las va a resolver igual si las buscás como X-Sovra-Signature.

La firma cubre el cuerpo, y el cuerpo incluye timestamp, pero no hay una cabecera de timestamp aparte. Para protegerte de una reinyección, deduplicá por id. También podés rechazar sobres cuyo timestamp sea demasiado viejo, siempre que la ventana sea más ancha que el calendario de reintentos (~1,5 horas).

Catálogo de eventos

Todos los eventos llegan con el mismo sobre. Lo propio de cada evento va en data:

{
  "event": "credential.issued",
  "id": "4f3379d8-0fab-4631-975c-c36a68528bd4",
  "timestamp": "2026-08-26T04:41:33.108371Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {}
}

El id es el mismo en todos los reintentos de un evento: es el valor para descartar repetidos.

Evento Te avisa que… Ciclo de vida
identity.did-generated Tu workspace quedó listo para operar. Primeros pasos
credential.issued Un holder canjeó una oferta y recibió la credencial. Estados de la credencial
credential.revoked Una revocación quedó aplicada en la cadena. Estados de la credencial
credential.suspended Una suspensión quedó aplicada en la cadena. Estados de la credencial
credential.unsuspended Se levantó una suspensión en la cadena. Estados de la credencial
credential.status-change-failed Un cambio de estado que pediste no se pudo aplicar. Estados de la credencial
document.status-changed Un documento firmado quedó anclado (o el anclaje falló). Estados del documento
presentation.verified Una presentación pasó todas las validaciones. Estados de la sesión
presentation.failed Una presentación fue rechazada. Estados de la sesión

No hay webhook para el registro on-chain de un esquema: eso se consulta con GET /api/v1/issuer/schemas, mirando registration_status.

Detalles del sobre: campos y fechas
Campo Tipo Descripción
event string Tipo de evento.
id uuid Único por evento. El mismo en todos los endpoints y en todos los reintentos de ese evento, así que es el valor sobre el que deduplicar.
timestamp string Cuándo se emitió el evento (ISO 8601, UTC, con microsegundos). No cambia entre reintentos.
workspace_id uuid El workspace al que pertenece el evento.
data object El contenido específico del evento.

Las fechas dentro de data son ISO 8601 UTC. La mayoría va truncada al segundo (2026-10-14T14:21:07Z); status_at lleva microsegundos (2026-10-14T14:21:07.318402Z).

El orden de las claves del cuerpo crudo no es parte del contrato. Los ejemplos de esta página ponen event primero porque se lee mejor.

Entrega y reintentos

Respondé 2xx apenas guardaste el evento, en menos de 5 segundos, y procesalo después. Si algo falla de tu lado, respondé 5xx: Sovra reintenta hasta 8 veces durante ~1,5 horas. Pasado eso, el evento se pierde.

Qué hace Sovra con cada respuesta, y qué se relee en cada intento

Cada evento es un POST por cada endpoint suscrito y habilitado. Cada intento tiene un timeout de recepción de 5 segundos, y el código de respuesta decide qué pasa después:

Respuesta de tu servidor Qué hace Sovra
2xx Entregado. Fin.
4xx (cualquiera, incluidos 408 y 429) Se descarta y no se reintenta nunca. Se interpreta como un bug del lado que recibe.
5xx, cualquier otro código, timeout o error de conexión Se reintenta.
3xx Se sigue el redirect. 301/302/303 se reenvían como GET; 307/308 conservan el POST. La respuesta final se clasifica con esta misma tabla. Apuntá el endpoint a su URL final.

Son 8 intentos en total, con un backoff que crece rápido: entre el primero y el último pasan en total ~1,5 horas. Después de eso la entrega se descarta y el evento no vuelve. Un endpoint caído más tiempo que eso pierde el evento, y la única forma de ponerse al día es consultar la API.

El endpoint se busca de nuevo en cada intento:

  • Un endpoint borrado, deshabilitado o desuscrito del evento después de que el evento se emitió se saltea en silencio.
  • Una URL cambiada la usan los reintentos pendientes.
  • Un secreto rotado firma los reintentos pendientes.

Un endpoint deshabilitado en el momento en que el evento se emite no recibe ese evento nunca, aunque después se vuelva a habilitar.

Orden y consistencia

No hay garantía de orden. Las entregas corren en paralelo y cada endpoint reintenta con su propio calendario: un credential.revoked puede llegar antes que un credential.issued demorado. Ordená por timestamp, o por status_at donde exista.

Si recibiste el evento, el estado que describe ya está confirmado, y un GET sobre el recurso devuelve ese mismo estado o uno posterior.

Cuando nada está suscrito a un evento, el evento no se guarda ni se encola en ningún lado.

Qué trae cada evento

identity.did-generated

Tu workspace terminó de aprovisionarse: su DID did:sovra:… quedó registrado on-chain y ya podés crear esquemas, ofertas y verificaciones. Se emite una sola vez.

Payload y detalles de identity.did-generated

No se dispara si el aprovisionamiento falla: no hay evento de falla. Un aprovisionamiento reintentado desde el dashboard emite el evento cuando tiene éxito.

Los endpoints se buscan en el momento en que el evento se emite, y un workspace recién creado no tiene ninguno. En la práctica, este evento solo le llega a un endpoint que ya existía mientras el aprovisionamiento corría, o antes del reintento de uno que había fallado.

Campo de data Tipo Nulo Descripción
did string no El DID del workspace: did:sovra:0x + 40 hex en minúscula.
provisioned_at string no Cuándo terminó el aprovisionamiento.
{
  "event": "identity.did-generated",
  "id": "5b0e7c1e-2f0a-4a51-9a39-0f6f2d3c8e11",
  "timestamp": "2026-08-26T04:10:02.482913Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "did": "did:sovra:0xcda79e1ee5612c230a6faf68236e3679b0579bae",
    "provisioned_at": "2026-08-26T04:10:01Z"
  }
}

credential.issued

La wallet del holder canjeó la oferta y la credencial quedó emitida. Trae el credential_id (el mismo que te devolvió la oferta), el format (vc+sd-jwt o mso_mdoc) y la credencial completa en credential.

Payload y campos de credential.issued

No se dispara cuando se crea la oferta, cuando una oferta vence sin canjearse, ni cuando el canje falla (prueba inválida, oferta vencida, oferta ya canjeada).

Campo de data Tipo Nulo Descripción
credential_id uuid no El mismo que devolvió POST /credential-offer. Sirve para GET /api/v1/issuer/credentials/{id} y para los endpoints de estado.
holder_did string no El DID del holder, tomado de la prueba de la wallet.
schema_type string no El credential_type del esquema.
format string no vc+sd-jwt o mso_mdoc. Es el campo sobre el que bifurcar la lógica.
doc_type string — Solo cuando format es mso_mdoc. El docType del mDoc.
issued_at string no Momento de la emisión.
expires_at string sí El vencimiento que lleva la credencial. null si el esquema no tiene validity_period y la oferta no fijó valid_until.
credential string no La credencial tal como se le entregó al holder. En vc+sd-jwt, el SD-JWT <jwt>~<disclosure>~…~. En mso_mdoc, el IssuerSigned en CBOR, base64url sin padding.
attachment object — Solo cuando la credencial lleva un adjunto (ver abajo).
{
  "event": "credential.issued",
  "id": "4f3379d8-0fab-4631-975c-c36a68528bd4",
  "timestamp": "2026-08-26T04:41:33.108371Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "credential_id": "b662aaad-d940-48fb-be9e-7194c76210ff",
    "holder_did": "did:sovra:0x90833e201da2dd3c146619217f18a85bbd12f274",
    "schema_type": "DrivingLicence",
    "format": "vc+sd-jwt",
    "issued_at": "2026-08-26T04:41:32Z",
    "expires_at": "2027-08-26T04:41:32Z",
    "credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6InZjK3NkLWp3dCJ9…~WyJxN0NfZ0x…~"
  }
}

En mDoc se suma doc_type, y credential es el IssuerSigned en CBOR, base64url sin padding: no es un JWT y no tiene puntos ni caracteres ~.

{
  "event": "credential.issued",
  "id": "e0b1c2d3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "timestamp": "2026-09-28T13:02:11.114208Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "credential_id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
    "holder_did": "did:sovra:0x90833e201da2dd3c146619217f18a85bbd12f274",
    "schema_type": "DrivingLicence",
    "format": "mso_mdoc",
    "doc_type": "org.iso.18013.5.1.mDL",
    "issued_at": "2026-09-28T13:02:11Z",
    "expires_at": "2036-09-28T13:02:11Z",
    "credential": "ompuYW1lU3BhY2VzoXFvcmcuaXNvLjE4MDEzLjUuMYbYGFhT…"
  }
}

Para decodificarlo e inspeccionarlo, mirá Cómo inspeccionar una credencial.

Los adjuntos no viajan en el webhook. Un esquema vc+sd-jwt puede declarar un claim attachment, que lleva un PDF como data URI de hasta 560.000 bytes. En la entrega, la disclosure del adjunto se saca del credential, pero su digest queda en el array _sd firmado: la firma sigue verificando y el claim se lee como retenido. La credencial que tiene la wallet sí incluye el adjunto. El campo attachment describe lo que se sacó:

Campo de attachment Tipo Descripción
claim string La clave del claim que se sacó.
type string Siempre attachment.
media_type string El tipo de medio del archivo, p. ej. application/pdf.
bytes integer El tamaño del archivo decodificado, en bytes.
"attachment": { "claim": "titulo_pdf", "type": "attachment",
                "media_type": "application/pdf", "bytes": 184213 }

credential.revoked / credential.suspended / credential.unsuspended

Cuando pedís revocar, suspender o reactivar una credencial, la API responde 202 y el cambio se escribe en la cadena en segundo plano. Estos eventos te avisan que el cambio ya quedó aplicado. Hasta entonces, los verificadores siguen viendo el estado anterior.

Evento Transición
credential.revoked issued → revoked, o suspended → revoked. Es permanente.
credential.suspended issued → suspended
credential.unsuspended suspended → issued

Llegan tanto si el cambio se hizo por API como desde el dashboard.

Payload y detalles de los cambios de estado

El pedido llega por PUT /api/v1/issuer/credentials/{id}/status/{status} —con {status} en revoked, suspended o issued para levantar una suspensión— o desde el dashboard. Devuelve 202 al instante, con el destino en pending_status. Cuando la transacción confirma, el status de la credencial cambia y el evento se emite.

Una credencial admite un cambio pendiente a la vez.

No se disparan cuando el cambio se pide, ni en un intento fallido que va a reintentarse —los intentos fallan en silencio hasta el quinto y último—, ni cuando el último intento falla: en ese caso se envía credential.status-change-failed.

El payload no trae un campo status, porque el nombre del evento es el estado nuevo.

Campo de data Tipo Nulo Descripción
credential_id uuid no La credencial.
holder_did string no El DID del holder.
schema_type string no El credential_type del esquema.
status_at string (µs) no Cuándo se aplicó el estado nuevo.
{
  "event": "credential.revoked",
  "id": "71e4a0c9-3b2d-4f8e-a6c5-0d9b8e7f6a52",
  "timestamp": "2026-08-26T05:02:11.640277Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "credential_id": "b662aaad-d940-48fb-be9e-7194c76210ff",
    "holder_did": "did:sovra:0x90833e201da2dd3c146619217f18a85bbd12f274",
    "schema_type": "DrivingLicence",
    "status_at": "2026-08-26T05:02:11.638904Z"
  }
}

credential.status-change-failed

El cambio de estado que pediste no se pudo escribir en la cadena después de cinco intentos. El estado de la credencial quedó como estaba y ya podés volver a pedirlo. Si revocás por API, suscribite a este evento: sin él, una revocación que no llegó a la cadena se ve igual que una que sí llegó.

Payload y campos de credential.status-change-failed

El pending_status de la credencial se limpia, y el motivo queda en status_change_error, que devuelve GET /api/v1/issuer/credentials/{id}.

Campo de data Tipo Nulo Descripción
credential_id uuid no La credencial.
holder_did string no El DID del holder.
schema_type string no El credential_type del esquema.
requested_status string no El estado que se había pedido: revoked, suspended o issued.
status string no El estado de la credencial, sin cambios: issued o suspended.
status_at string (µs) no Cuándo se dio por vencido el cambio.
{
  "event": "credential.status-change-failed",
  "id": "0f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f",
  "timestamp": "2026-08-26T05:09:52.002914Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "credential_id": "b662aaad-d940-48fb-be9e-7194c76210ff",
    "holder_did": "did:sovra:0x90833e201da2dd3c146619217f18a85bbd12f274",
    "schema_type": "DrivingLicence",
    "requested_status": "revoked",
    "status": "issued",
    "status_at": "2026-08-26T05:09:52.001377Z"
  }
}

document.status-changed

Un documento firmado nace en signed y todavía no se puede entregar: un verificador lo rechaza hasta que esté anclado en la cadena. Este evento llega una sola vez por documento, con el resultado final:

  • anchored: el documento quedó registrado. Es la señal de que lo podés entregar.
  • failed: el anclaje falló después de cinco intentos. Hay que volver a emitirlo.
Payload y detalles de document.status-changed

La emisión (POST /api/v1/issuer/documents, o el dashboard) responde al instante con el documento en signed; después se manda la transacción y, cuando se resuelve, el estado nuevo y este evento se confirman juntos.

Ningún documento falla por tiempo. Uno que espera en una cola larga sigue en signed; nada lo marca failed por tardar. El anclaje tiene un techo de throughput —del orden de 5 documentos por bloque y por nodo—, así que un lote grande puede tardar varios minutos en resolverse.

Campo de data Tipo Nulo Descripción
document_id uuid no El documento, tal como lo devolvió la emisión.
status string no anchored o failed.
schema_type string no El credential_type del esquema de documento.
tx_hash string sí La transacción del anclaje, 0x + 64 hex. null cuando es failed. No está en la respuesta de emisión: llega acá.
anchored_at string sí Cuándo quedó registrado. null cuando es failed.
status_at string (µs) no Cuándo cambió el estado en Sovra.
{
  "event": "document.status-changed",
  "id": "d2c3b4a5-9687-4e1f-a0b9-c8d7e6f5a4b3",
  "timestamp": "2026-08-21T14:12:08.401552Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "document_id": "63813a91-6986-46bf-9f23-128a6598cd82",
    "status": "anchored",
    "schema_type": "Document",
    "tx_hash": "0x9c93c1eec04ae7e4566b4ee394ac518b33c36b0ffd324276289e998eed72f8ca",
    "anchored_at": "2026-08-21T14:12:08Z",
    "status_at": "2026-08-21T14:12:08.399871Z"
  }
}
{
  "event": "document.status-changed",
  "id": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
  "timestamp": "2026-08-21T14:19:44.770318Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "document_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "failed",
    "schema_type": "Document",
    "tx_hash": null,
    "anchored_at": null,
    "status_at": "2026-08-21T14:19:44.768902Z"
  }
}

presentation.verified

Una wallet presentó una credencial y pasó todos los controles: firma del emisor, titularidad, vigencia, revocación y lo que pediste en la consulta. Trae el verification_id (el session_id de tu sesión) y, en credentials, solo los claims que pediste.

Payload y campos de presentation.verified

Los controles completos son: la firma del emisor, el binding del holder, el nonce y la audiencia, las disclosures o los digests de valor, el vencimiento, el estado de revocación y suspensión, y la coincidencia con el DCQL. La sesión pasa a completed.

No se dispara cuando una sesión vence sin que nadie presente —pasa a expired sin webhook—, cuando la presentación va a una sesión inexistente o ya resuelta, ni cuando hay un error interno durante la verificación.

Campo de data Tipo Nulo Descripción
verification_id uuid no La sesión. Es el mismo valor que el session_id que devolvió POST /api/v1/verifier/verifications.
holder_did string no El DID del holder que presentó. En mDoc sale del namespace meta de la credencial, no de la deviceKey.
success boolean no Siempre true.
credentials array no Una entrada por consulta de credencial del DCQL.
completed_at string no Cuándo se completó la sesión.

Cada entrada de credentials:

Campo Tipo Descripción
id string El id de la consulta DCQL: la etiqueta que elegiste.
format string El formato que pidió la consulta: dc+sd-jwt, vc+sd-jwt o mso_mdoc.
claims object Solo los claims que la consulta pidió, indexados por path. SD-JWT: el path del DCQL unido con ., p. ej. address.locality. mDoc: <namespace>.<element_identifier>, p. ej. org.iso.18013.5.1.family_name. En mDoc, los byte strings van en base64url y las fechas como string ISO 8601.
{
  "event": "presentation.verified",
  "id": "1157c346-dfc9-4e5d-9dd0-5c28d7f24ce9",
  "timestamp": "2026-08-26T04:47:31.165773Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "verification_id": "e2d16450-42e8-46a9-ae92-d72af51a7435",
    "holder_did": "did:sovra:0x90833e201da2dd3c146619217f18a85bbd12f274",
    "success": true,
    "completed_at": "2026-08-26T04:47:31Z",
    "credentials": [
      {
        "id": "training_v2",
        "format": "dc+sd-jwt",
        "claims": { "given_name": "Ana", "employer.name": "Acme S.A." }
      }
    ]
  }
}

En mDoc, las claves de claims llevan el namespace como prefijo: si pediste ["org.iso.18013.5.1", "family_name"], la clave es "org.iso.18013.5.1.family_name", no "family_name", porque dos namespaces pueden tener un elemento con el mismo nombre. Una integración que asume la forma de SD-JWT falla acá en silencio.

{
  "event": "presentation.verified",
  "data": {
    "verification_id": "e2d16450-42e8-46a9-ae92-d72af51a7435",
    "holder_did": "did:sovra:0x90833e201da2dd3c146619217f18a85bbd12f274",
    "success": true,
    "completed_at": "2026-09-28T13:05:12Z",
    "credentials": [
      {
        "id": "licencia",
        "format": "mso_mdoc",
        "claims": {
          "org.iso.18013.5.1.family_name": "Lovelace",
          "org.iso.18013.5.1.given_name": "Ada",
          "org.iso.18013.5.1.age_over_18": true
        }
      }
    ]
  }
}

presentation.failed

Una wallet presentó, pero algún control falló. El campo error dice cuál, por ejemplo credential_revoked o missing_required_claim:first_name. La causa y la solución de cada código están en Errores de verificación.

Payload, campos y lista de códigos de presentation.failed

La sesión pasa a failed. Valen las mismas exclusiones que en presentation.verified, con un agregado: una presentación que llega a una sesión todavía pending pero ya pasada de su vencimiento sí dispara este evento, con session_expired.

Campo de data Tipo Nulo Descripción
verification_id uuid no La sesión.
holder_did string sí El DID del holder, si se llegó a establecer antes de la falla; null si no (por ejemplo, con malformed_vp_token, unknown_issuer o session_expired).
success boolean no Siempre false.
error string no La etiqueta de la falla (tabla abajo). Algunas llevan un detalle después de :.
completed_at string no Cuándo falló la sesión.
{
  "event": "presentation.failed",
  "id": "e678e20a-be4c-459a-b0a7-4b04783cb8d3",
  "timestamp": "2026-08-26T04:45:07.584992Z",
  "workspace_id": "bfe85e0d-c2da-4ccd-bd99-d26827f7e45e",
  "data": {
    "verification_id": "183ee078-69b7-4fa5-9a6f-b40ddbb59ce5",
    "holder_did": "did:sovra:0x90833e201da2dd3c146619217f18a85bbd12f274",
    "success": false,
    "error": "missing_required_claim:first_name",
    "completed_at": "2026-08-26T04:45:07Z"
  }
}
error Qué significa
session_expired Presentó después del expires_at de la sesión.
invalid_dcql_query El DCQL de la sesión no sirve para esta presentación.
malformed_vp_token El vp_token no es una respuesta DCQL ni una presentación bien formada.
unknown_issuer El emisor de la credencial no es un emisor conocido y confiable.
credential_signature_invalid La firma del emisor no verifica, o el docType de un mDoc no coincide con su MSO.
invalid_disclosure Una disclosure de SD-JWT, o un digest de valor de mDoc, no coincide con lo que el emisor firmó.
missing_mandatory_element:<namespace>[.<elemento>] Al mDoc le falta un elemento que Sovra exige.
credential_expired La credencial venció.
credential_revoked El emisor la revocó.
credential_suspended El emisor la suspendió.
status_check_failed El estado on-chain no pudo leerse. Es un problema del lado de Sovra; la credencial puede ser válida.
holder_did_missing La credencial no nombra holder.
holder_did_unresolvable El DID del holder no pudo resolverse. Problema del lado de Sovra, o un holder no registrado.
holder_did_mismatch El holder de la credencial y el del KB-JWT no coinciden.
holder_key_mismatch La presentación no la firmó la clave del holder.
holder_nonce_mismatch El KB-JWT no es para el nonce de esta sesión.
holder_audience_mismatch El KB-JWT está dirigido a otro verificador.
holder_iat_out_of_range El iat del KB-JWT está desfasado más de 5 minutos.
sd_hash_mismatch El KB-JWT no se compromete con el SD-JWT presentado.
device_mac_unsupported El mDoc usó autenticación de dispositivo por MAC, que no está soportada.
unsupported_device_auth_alg El algoritmo de la firma de dispositivo del mDoc no está soportado.
format_mismatch[:<formato>] La credencial presentada no está en el formato que pidió la consulta.
doctype_mismatch El docType del mDoc no es el que pidió la consulta.
missing_required_claim:<path> La credencial no lleva un claim que la consulta pidió.

Buenas prácticas

  • Respondé rápido y procesá después. Tenés 5 segundos.
  • Descartá repetidos por id. Los reintentos repiten el mismo evento.
  • Nunca respondas 4xx por un problema tuyo. Usá 5xx para que Sovra reintente.
  • Correlacioná por el identificador de negocio: credential_id, document_id o verification_id. Guardalo cuando creás la oferta, el documento o la sesión, antes de mostrar el QR.
  • Guardá el payload crudo y tu veredicto. No hay historial de entregas del lado de Sovra.
  • Tené un plan B. Si tu endpoint estuvo caído más de ~1,5 horas, reconciliá con GET /api/v1/issuer/credentials, GET /api/v1/issuer/documents y GET /api/v1/verifier/verifications.

Si algo no funciona

No llegan los webhooks

Revisá, en este orden:

  1. ¿Hay un endpoint habilitado? Uno deshabilitado en el momento en que el evento se emite no lo recibe nunca, aunque después lo vuelvas a habilitar.
  2. ¿Está suscrito a ese evento? No hay comodín. Es la causa número uno de “no me llega el evento nuevo”: document.status-changed y credential.status-change-failed no le llegan a un endpoint creado antes de que existieran.
  3. ¿Es accesible desde internet? localhost no sirve; usá un túnel (ngrok, Cloudflare Tunnel) durante el desarrollo.
  4. ¿Respondés 2xx en menos de 5 segundos? Más lento cuenta como fallo.
  5. ¿Devolvés 4xx? Descarta el evento sin reintentos. Si tu validación de firma rechaza por un secreto mal configurado, perdés el evento.
  6. ¿Tu URL redirige? Un 301/302/303 se reenvía como GET y el cuerpo se pierde. Apuntá el endpoint a su URL final.

Pasados los 8 intentos (~1,5 horas), el evento se perdió y hay que reconciliar con la API.

La firma nunca valida
  1. Estás firmando un cuerpo re-serializado. Usá el cuerpo crudo (express.raw(), request.body() en FastAPI).
  2. El secreto es de otro endpoint. Cada endpoint tiene el suyo. Si varios endpoints o workspaces apuntan a la misma URL, elegí el secreto según el workspace_id del payload y la URL por la que entró.
  3. Le sacaste el prefijo whsec_ al secreto. La clave del HMAC es el string completo.

Implementación de referencia

Un receptor completo en Node.js, con firma, idempotencia y un switch por evento
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.SOVRA_WEBHOOK_SECRET;
const procesados = new Set(); // en producción: Redis o una tabla

function firmaValida(crudo, recibida) {
  const esperada =
    "sha256=" + crypto.createHmac("sha256", SECRET).update(crudo).digest("hex");
  const a = Buffer.from(recibida ?? "");
  const b = Buffer.from(esperada);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post(
  "/webhooks/sovra",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!firmaValida(req.body, req.get("x-sovra-signature"))) {
      console.warn("Webhook con firma inválida", req.body.toString("utf8"));
      return res.sendStatus(401);
    }

    const evento = JSON.parse(req.body.toString("utf8"));

    // Idempotencia: los reintentos repiten el mismo `id`.
    if (procesados.has(evento.id)) return res.sendStatus(200);
    procesados.add(evento.id);

    res.sendStatus(200);           // primero acusar recibo…
    manejar(evento).catch(console.error); // …después trabajar
  },
);

async function manejar({ event, data }) {
  switch (event) {
    case "credential.issued":
      await db.tramites.updateBySovraId(data.credential_id, {
        estado: "emitida",
        holder_did: data.holder_did,
        sd_jwt: data.credential, // única entrega: guardalo
      });
      break;

    case "credential.revoked":
    case "credential.suspended":
    case "credential.unsuspended":
      await db.tramites.updateBySovraId(data.credential_id, {
        estado: event.split(".")[1], // ya confirmado on-chain
      });
      break;

    case "credential.status-change-failed":
      // El 202 que recibiste no se concretó: el estado quedó como estaba.
      await db.tramites.updateBySovraId(data.credential_id, {
        estado: data.status,
        error_cambio_estado: data.requested_status,
      });
      break;

    case "document.status-changed":
      // Solo `anchored` es entregable; `failed` hay que volver a emitirlo.
      await db.documentos.updateBySovraId(data.document_id, {
        estado: data.status,
        tx_hash: data.tx_hash,
        entregable: data.status === "anchored",
      });
      break;

    case "presentation.verified":
      await db.verificaciones.updateBySovraId(data.verification_id, {
        estado: "aprobada",
        datos: data.credentials[0]?.claims ?? {},
      });
      break;

    case "presentation.failed":
      await db.verificaciones.updateBySovraId(data.verification_id, {
        estado: "rechazada",
        motivo: data.error,
      });
      break;

    case "identity.did-generated":
      await db.workspaces.marcarListo(data.did);
      break;

    default:
      console.info("Evento no manejado:", event);
  }
}

Si emitís en los dos formatos, bifurcá credential.issued por data.format (vc+sd-jwt o mso_mdoc): en mDoc, data.credential es CBOR en base64url, no un SD-JWT.

Type to search…

↑↓ navigate↵ selectEsc close