Everdeen Passport
English
Start free

Webhooks

When something changes in your company's data, we send an HTTPS request to every endpoint that subscribes to that event. Add endpoints in the dashboard under Integrations.

Request

POSTSent over HTTPS to the endpoint URL you saved. Redirects are not followed.
Content-TypeThe body is the event as JSON, described below.
Evd-SignatureWhen the request was signed, and its HMAC-SHA256 signature.

Payload

Every event uses the same envelope. The data field holds the affected record.

{
  "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
  }
}
FieldDescription
event_idUnique for each event. Skip an ID you have already processed.
typeThe event name, from the list at the end of this page.
created_atWhen the event happened, in UTC.
testTrue when a test key caused the event.
dataThe affected record, as its GET endpoint returns it.

Verify the signature

Each endpoint has its own signing secret, shown once when you add the endpoint. Check every request before you act on it:

  1. Read t (Unix time in seconds) and v1 from the Evd-Signature header.
  2. Compute HMAC-SHA256 with your secret over t, a full stop, and the raw request body, exactly as received.
  3. Compare the result with v1 in constant time.
  4. Reject the request if t is more than five minutes from your clock.
  5. Skip an event ID you have already processed, then respond with a 2xx status.
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;
}

Check your code

With this secret, timestamp, and body, your code should compute this v1 value.

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

Retries and replay

Respond quickly and do slow work afterwards. A response outside 2xx, a redirect, or a timeout counts as a failed attempt. We retry up to 8 times over about 24 hours, then mark the delivery as failed. You can replay any delivery from the dashboard or the API.

Events

Choose which events each endpoint receives.

EventDescription
product.createdA product was added.
product.updatedA product's details changed.
item.createdA serial or lot was added to a product.
item.updatedA serial or lot changed.
item.publishedA serial or lot's passport went live.
item.withdrawnA serial or lot was withdrawn.
compliance.createdA certificate or compliance record was added.
compliance.updatedA compliance record changed.
document.uploadedA document was uploaded.
extraction.completedData extraction from a document finished.
review.requiredA change is waiting for review.
review.approvedA reviewer approved a change.
review.rejectedA reviewer rejected a change.
passport.publishedA product passport was published.
passport.withdrawnA product passport was withdrawn.
certificate.expiringA certificate expires within 30 days.
certificate.expiredA certificate has expired.