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

> Documentation Index
> Fetch the complete documentation index at: https://sovra-id-docs-1044960690985.us-central1.run.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

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.

> **No hay historial ni reenvío**
>
> Todavía no hay evento de prueba, historial de entregas ni reenvío manual. Si perdés
> un evento, la única forma de ponerte al día es consultar la API.

- 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:

```js
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.

```python
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}
```

```http
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`:

```json
{
  "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`](#identitydid-generated) | Tu workspace quedó listo para operar. | [Primeros pasos](https://sovra-id-docs-1044960690985.us-central1.run.app/primeros-pasos/) |
| [`credential.issued`](#credentialissued) | Un holder canjeó una oferta y recibió la credencial. | [Estados de la credencial](https://sovra-id-docs-1044960690985.us-central1.run.app/credenciales/estados-y-revocacion/) |
| [`credential.revoked`](#credentialrevoked--credentialsuspended--credentialunsuspended) | Una revocación quedó aplicada en la cadena. | [Estados de la credencial](https://sovra-id-docs-1044960690985.us-central1.run.app/credenciales/estados-y-revocacion/) |
| [`credential.suspended`](#credentialrevoked--credentialsuspended--credentialunsuspended) | Una suspensión quedó aplicada en la cadena. | [Estados de la credencial](https://sovra-id-docs-1044960690985.us-central1.run.app/credenciales/estados-y-revocacion/) |
| [`credential.unsuspended`](#credentialrevoked--credentialsuspended--credentialunsuspended) | Se levantó una suspensión en la cadena. | [Estados de la credencial](https://sovra-id-docs-1044960690985.us-central1.run.app/credenciales/estados-y-revocacion/) |
| [`credential.status-change-failed`](#credentialstatus-change-failed) | Un cambio de estado que pediste **no** se pudo aplicar. | [Estados de la credencial](https://sovra-id-docs-1044960690985.us-central1.run.app/credenciales/estados-y-revocacion/) |
| [`document.status-changed`](#documentstatus-changed) | Un documento firmado quedó anclado (o el anclaje falló). | [Estados del documento](https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/estados-y-revocacion/) |
| [`presentation.verified`](#presentationverified) | Una presentación pasó todas las validaciones. | [Estados de la sesión](https://sovra-id-docs-1044960690985.us-central1.run.app/verificadores/estados-de-la-sesion/) |
| [`presentation.failed`](#presentationfailed) | Una presentación fue rechazada. | [Estados de la sesión](https://sovra-id-docs-1044960690985.us-central1.run.app/verificadores/estados-de-la-sesion/) |

No hay webhook para el registro on-chain de un esquema: eso se consulta con
[`GET /api/v1/issuer/schemas`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/list-schemas/), mirando `registration_status`.

> **Suscribite a los eventos de falla**
>
> `credential.status-change-failed` y `document.status-changed` con `status: "failed"`
> son la única forma de enterarte de que una operación que respondió `202` o `201`
> terminó mal.

| 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.

> **Un 4xx pierde el evento**
>
> Cualquier `4xx` (incluidos `408` y `429`) hace que Sovra **descarte el evento sin
> reintentar**. Si tu validación de firma devuelve `401` porque el secreto está mal
> configurado, perdés el evento para siempre. Durante la puesta en marcha, registrá los
> payloads que rechaces.

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.

**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.

**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. |

```json
{
  "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`.

> **Única entrega**
>
> La credencial firmada no se guarda del lado de Sovra ni se puede volver a pedir. Si
> tu sistema la necesita, guardala acá. Lleva todos los datos del holder: tratala como
> dato personal.

**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). |

### SD-JWT VC

```json
{
  "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…~"
  }
}
```

### mDoc

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 `~`.

```json
{
  "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](https://sovra-id-docs-1044960690985.us-central1.run.app/errores/credenciales/#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. |

```json
"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.

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`](#credentialstatus-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. |

```json
{
  "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ó.

El `pending_status` de la credencial se limpia, y el motivo queda en
`status_change_error`, que devuelve
[`GET /api/v1/issuer/credentials/{id}`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/get-credential/).

| 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. |

```json
{
  "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.

La emisión ([`POST /api/v1/issuer/documents`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/issue-document/), 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. |

### anchored

```json
{
  "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"
  }
}
```

### failed

```json
{
  "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**.

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`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/create-verification/). |
| `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. |

### SD-JWT VC

```json
{
  "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." }
      }
    ]
  }
}
```

### mDoc

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.

```json
{
  "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](https://sovra-id-docs-1044960690985.us-central1.run.app/errores/verificacion/#errores-de-presentación).

La sesión pasa a `failed`. Valen las mismas exclusiones que en
[`presentation.verified`](#presentationverified), 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. |

```json
{
  "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`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/list-credentials/),
  [`GET /api/v1/issuer/documents`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/list-documents/) y
  [`GET /api/v1/verifier/verifications`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/list-verifications/).

## Si algo no funciona

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.

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

```js
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.

Source: https://sovra-id-docs-1044960690985.us-central1.run.app/webhooks/index.mdx
