Everdeen Passport
Español
Empieza gratis

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

POSTSe envía por HTTPS a la URL del endpoint que guardaste. No se siguen redirecciones.
Content-TypeEl cuerpo es el evento en JSON, descrito más abajo.
Evd-SignatureCuá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
  }
}
CampoDescripción
event_idÚnico para cada evento. Ignora un ID que ya hayas procesado.
typeEl nombre del evento, de la lista al final de esta página.
created_atCuándo ocurrió el evento, en UTC.
testEs true cuando una clave de prueba causó el evento.
dataEl 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:

  1. Lee t (hora Unix en segundos) y v1 de la cabecera Evd-Signature.
  2. Calcula HMAC-SHA256 con tu secreto sobre t, un punto y el cuerpo sin procesar, tal como se recibió.
  3. Compara el resultado con v1 en tiempo constante.
  4. Rechaza la solicitud si t difiere de tu reloj en más de cinco minutos.
  5. 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.

secretexample-secret
t1767225600
body{"event_id":"evt_8KQ2M4ZP7T","type":"passport.published"}
v121cb13c5a2e80061c64fa3886778905d85dd5b87f2c5ceaa66d88b873dff5b40

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.

EventoDescripción
product.createdSe añadió un producto.
product.updatedCambiaron los datos de un producto.
item.createdSe añadió un número de serie o lote a un producto.
item.updatedCambió un número de serie o lote.
item.publishedSe publicó el pasaporte de un número de serie o lote.
item.withdrawnSe retiró un número de serie o lote.
compliance.createdSe añadió un certificado o registro de cumplimiento.
compliance.updatedCambió un registro de cumplimiento.
document.uploadedSe subió un documento.
extraction.completedTerminó la extracción de datos de un documento.
review.requiredUn cambio espera revisión.
review.approvedUn revisor aprobó un cambio.
review.rejectedUn revisor rechazó un cambio.
passport.publishedSe publicó el pasaporte de un producto.
passport.withdrawnSe retiró el pasaporte de un producto.
certificate.expiringUn certificado vence en 30 días o menos.
certificate.expiredUn certificado ha vencido.