Suscribirse a un evento
Solo aplica si usas suscripciones
Este endpoint es parte del esquema de suscripciones por evento (beta). Si usas la URL única del panel (el esquema estándar), no lo necesitas: todos los eventos ya te llegan ahí automáticamente.
Registra una URL para recibir aviso cuando ocurra un evento. Una suscripción es un tipo de evento — para recibir varios, registra varios.
La URL tiene que aceptar POST con application/json. Firmame espera un 200; cualquier otra
cosa se considera un fallo y se reintenta con backoff exponencial. Hasta 30 intentos o 10 minutos entre uno y otro. Una URL
inválida no se reintenta nunca.
El payload de cada evento está en la sección de Webhooks.
Autenticación
signmage Cada petición lleva Authorization: signmage {webId}:{firma}, donde firma es el Base64 de
HMAC-SHA256(apiKey, cadenaFirmada).
Qué va dentro de cadenaFirmada depende de la petición:
| Petición | cadenaFirmada |
|---|---|
GET | La URI completa incluyendo el query string, exactamente como se envía |
POST con JSON | El cuerpo JSON, re-serializado compacto (sin espacios ni salto de línea final) |
POST multipart | El SHA-256 en Base64 del archivo, que además se manda en el header Content-SHA256 |
Dos detalles que conviene resolverlos desde el principio:
- En
GET, la URI se firma tal como se envía, así que el orden y el encoding de los parámetros importan. - En
POST, la comparación se hace contra tu JSON re-serializado en forma compacta. Manda JSON compacto y canónico para que las firmas coincidan.
Una firma que no coincide devuelve 401 con el cuerpo vacío. Como la misma respuesta cubre un
web ID desconocido, una llave inactiva y una firma que no coincide, revisa las tres cosas al
diagnosticar.
En: header
Cuerpo de la petición
application/json
Definiciones de TypeScript
Usa el tipo request body en TypeScript.
Cuerpo de la respuesta
application/json
application/json
curl -X POST "https://example.com/api/v1/webhooks" \ -H "Content-Type: application/json" \ -d '{ "url": "https://tu-servidor.com/hooks/firmame", "type": "document_completed" }'{ "id": "3f9a1c62-5d4e-4a1b-9c77-2e0b8f6d4a13"}