Webhooks
Cuando algo cambia en los datos de tu empresa, enviamos una solicitud HTTPS a cada endpoint suscrito a ese evento. Añade endpoints en el panel, en Integraciones.
Solicitud
POST | Se envía por HTTPS a la URL del endpoint que guardaste. No se siguen redirecciones. |
|---|---|
Content-Type | El cuerpo es el evento en JSON, descrito más abajo. |
Evd-Signature | Cuándo se firmó la solicitud y su firma HMAC-SHA256. |
Contenido
Todos los eventos usan la misma estructura. El campo data contiene el registro afectado.
{
"event_id": "evt_8KQ2M4ZP7T",
"type": "passport.published",
"created_at": "2026-10-31T02:15:00Z",
"test": false,
"data": {
"product_id": "prd_5F3K9W",
"version": 3,
"state": "PUBLISHED",
"signature_id": "sig_2RT8LQ",
"resolver_url": "https://pass.everdeenone.com/01/09506000134352",
"published_at": "2026-10-31T02:15:00Z",
"withdrawn_at": null
}
}
| Campo | Descripción |
|---|---|
event_id | Único para cada evento. Ignora un ID que ya hayas procesado. |
type | El nombre del evento, de la lista al final de esta página. |
created_at | Cuándo ocurrió el evento, en UTC. |
test | Es true cuando una clave de prueba causó el evento. |
data | El registro afectado, tal como lo devuelve su endpoint GET. |
Verificar la firma
Cada endpoint tiene su propio secreto de firma, que se muestra una sola vez al añadirlo. Comprueba cada solicitud antes de actuar:
- Lee t (hora Unix en segundos) y v1 de la cabecera Evd-Signature.
- Calcula HMAC-SHA256 con tu secreto sobre t, un punto y el cuerpo sin procesar, tal como se recibió.
- Compara el resultado con v1 en tiempo constante.
- Rechaza la solicitud si t difiere de tu reloj en más de cinco minutos.
- Ignora un ID de evento que ya hayas procesado y responde con un estado 2xx.
import crypto from "node:crypto";
// rawBody: the request body as received (a Buffer), before JSON parsing.
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(",").map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]),
);
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.`)
.update(rawBody)
.digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}import hashlib, hmac, time
# raw_body: the request body as received (bytes), before JSON parsing.
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t = parts.get("t", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(
secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))// rawBody: the request body as received, before JSON decoding.
func Verify(rawBody []byte, header, secret string) bool {
var t, v1 string
for _, p := range strings.Split(header, ",") {
k, v, _ := strings.Cut(p, "=")
switch k {
case "t":
t = v
case "v1":
v1 = v
}
}
ts, err := strconv.ParseInt(t, 10, 64)
if age := time.Now().Unix() - ts; err != nil || age > 300 || age < -300 {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(t + "."))
mac.Write(rawBody)
given, err := hex.DecodeString(v1)
return err == nil && hmac.Equal(given, mac.Sum(nil))
}import 'dart:convert';
import 'package:crypto/crypto.dart';
// rawBody: the request body as received, before JSON decoding.
bool verify(List<int> rawBody, String header, String secret) {
final parts = <String, String>{};
for (final p in header.split(',')) {
final i = p.indexOf('=');
if (i > 0) parts[p.substring(0, i)] = p.substring(i + 1);
}
final t = int.tryParse(parts['t'] ?? '');
final now = DateTime.now().millisecondsSinceEpoch ~/ 1000;
if (t == null || (now - t).abs() > 300) return false;
final mac = Hmac(sha256, utf8.encode(secret))
.convert([...utf8.encode('${parts['t']}.'), ...rawBody]);
final expected = mac.toString();
final given = parts['v1'] ?? '';
if (given.length != expected.length) return false;
var diff = 0;
for (var i = 0; i < given.length; i++) {
diff |= given.codeUnitAt(i) ^ expected.codeUnitAt(i);
}
return diff == 0;
}Comprueba tu código
Con este secreto, marca de tiempo y cuerpo, tu código debe calcular este valor v1.
secret | example-secret |
|---|---|
t | 1767225600 |
body | {"event_id":"evt_8KQ2M4ZP7T","type":"passport.published"} |
v1 | 21cb13c5a2e80061c64fa3886778905d85dd5b87f2c5ceaa66d88b873dff5b40 |
Reintentos y reenvío
Responde rápido y deja el trabajo lento para después. Una respuesta fuera de 2xx, una redirección o un tiempo agotado cuentan como intento fallido. Reintentamos hasta 8 veces durante unas 24 horas y luego marcamos la entrega como fallida. Puedes reenviar cualquier entrega desde el panel o la API.
Eventos
Elige qué eventos recibe cada endpoint.
| Evento | Descripción |
|---|---|
product.created | Se añadió un producto. |
product.updated | Cambiaron los datos de un producto. |
item.created | Se añadió un número de serie o lote a un producto. |
item.updated | Cambió un número de serie o lote. |
item.published | Se publicó el pasaporte de un número de serie o lote. |
item.withdrawn | Se retiró un número de serie o lote. |
compliance.created | Se añadió un certificado o registro de cumplimiento. |
compliance.updated | Cambió un registro de cumplimiento. |
document.uploaded | Se subió un documento. |
extraction.completed | Terminó la extracción de datos de un documento. |
review.required | Un cambio espera revisión. |
review.approved | Un revisor aprobó un cambio. |
review.rejected | Un revisor rechazó un cambio. |
passport.published | Se publicó el pasaporte de un producto. |
passport.withdrawn | Se retiró el pasaporte de un producto. |
certificate.expiring | Un certificado vence en 30 días o menos. |
certificate.expired | Un certificado ha vencido. |