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
POST | Sent over HTTPS to the endpoint URL you saved. Redirects are not followed. |
|---|---|
Content-Type | The body is the event as JSON, described below. |
Evd-Signature | When 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
}
}
| Field | Description |
|---|---|
event_id | Unique for each event. Skip an ID you have already processed. |
type | The event name, from the list at the end of this page. |
created_at | When the event happened, in UTC. |
test | True when a test key caused the event. |
data | The 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:
- Read t (Unix time in seconds) and v1 from the Evd-Signature header.
- Compute HMAC-SHA256 with your secret over t, a full stop, and the raw request body, exactly as received.
- Compare the result with v1 in constant time.
- Reject the request if t is more than five minutes from your clock.
- 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.
secret | example-secret |
|---|---|
t | 1767225600 |
body | {"event_id":"evt_8KQ2M4ZP7T","type":"passport.published"} |
v1 | 21cb13c5a2e80061c64fa3886778905d85dd5b87f2c5ceaa66d88b873dff5b40 |
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.
| Event | Description |
|---|---|
product.created | A product was added. |
product.updated | A product's details changed. |
item.created | A serial or lot was added to a product. |
item.updated | A serial or lot changed. |
item.published | A serial or lot's passport went live. |
item.withdrawn | A serial or lot was withdrawn. |
compliance.created | A certificate or compliance record was added. |
compliance.updated | A compliance record changed. |
document.uploaded | A document was uploaded. |
extraction.completed | Data extraction from a document finished. |
review.required | A change is waiting for review. |
review.approved | A reviewer approved a change. |
review.rejected | A reviewer rejected a change. |
passport.published | A product passport was published. |
passport.withdrawn | A product passport was withdrawn. |
certificate.expiring | A certificate expires within 30 days. |
certificate.expired | A certificate has expired. |