On this page
Why webhooks, not polling
A capture happens on someone's phone, at a moment you do not control. Sealing follows a few seconds later. Photo evidence webhooks let tryVidimus call your server when that happens, so your booking, claim or order shows the proof without anyone refreshing a page.
This article covers the events, the signature, retries and a working receiver. It is part of our developer guide to the photo evidence API. If you have not created a capture session yet, start with the four-step capture tutorial.
Events available
An endpoint subscribes to a list of events. Each message then carries an event field with the name of the one event it reports.
| Event | When it is sent | What to do with it |
|---|---|---|
| capture_session.completed | The person has finished the capture and the files are saved. The proof is not sealed yet. | Mark the capture as done in your interface. Do not use the proof yet. |
| proof.sealed | The proof is signed (C2PA) and timestamped (RFC 3161). | Store proof_id and verify_url next to your record. |
| proof.failed | The proof could not be sealed. | Read failure_code and retriable, then decide whether to ask for a new capture. |
| capture_session.rejected | An "after" capture was refused because another one already completed the same "before". | Nothing was saved and no credit was used. Create a new session if you need one. |
A capture that ends produces two messages, capture_session.completed then proof.sealed, each sent on its own. A fifth name, capture_session.expired, is accepted when you subscribe but is reserved for a later version: it is never sent yet.
Here is the body of proof.sealed. Your own identifier comes back unchanged in external_reference, which is how you find the record to update.
{
"event": "proof.sealed",
"proof_id": "prf_01m4akapdbe8e8qq3er9r5qwyj",
"external_reference": "booking_4471",
"party": "provider",
"stage": "pickup",
"status": "sealed",
"sealed_at": "2026-10-13T15:48:12.000Z",
"verify_url": "https://verify.tryvidimus.com/prf_01m4akapdbe8e8qq3er9r5qwyj"
}The proof.failed body replaces the last two fields with failure_code and retriable. The codes are hash_mismatch, invalid_media, signing_failed and timestamp_failed. Before reporting a failure, the service has already retried on its side, so a failed proof is not retried again by itself.
Declaring an endpoint
Declare the URL once, with a key that has the manage_webhooks scope. The URL must use HTTPS on a public domain name: no IP address and no localhost.
curl -X POST https://api.tryvidimus.com/v1/webhook-endpoints \
-H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://app.example.com/webhooks/proofs","events":["capture_session.completed","proof.sealed","proof.failed"]}'The answer contains the signing secret in clear, in the secret field. This is the only time it is shown: store it at once, in your secret manager. An endpoint belongs to the mode of the key that created it, so a test endpoint only receives test events.
Verifying webhook signatures
Anyone can send a POST to a public URL. Verify every call before you read its body. Each delivery carries three headers.
| Header | Meaning |
|---|---|
| X-Signature | t=<unix seconds>,v1=<signature>, with one v1 per active secret |
| X-Webhook-Id | Identifier of this delivery attempt |
| X-Event-Id | Identifier of the event, identical across retries |
The signature is the HMAC-SHA256, in lowercase hexadecimal, of the timestamp t, a dot and the raw body. The key is your endpoint secret, the whole string, including its whsec_ prefix. Compare the result with each v1 value, and reject the call if t is too old: the documentation gives the tolerance.
import { createHmac, timingSafeEqual } from 'node:crypto';
function isValid(header, rawBody, secret, toleranceSeconds = 300) {
const parts = header.split(',');
const t = Number(parts.find((p) => p.startsWith('t='))?.slice(2));
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
return parts
.filter((p) => p.startsWith('v1='))
.some((p) => {
const given = Buffer.from(p.slice(3), 'hex');
return given.length === expected.length && timingSafeEqual(given, expected);
});
}- Sign the raw body, byte for byte. A body that your framework parsed and serialized again will not match.
- Use a constant-time comparison, as in the example.
- Accept several v1 values. During a secret rotation, each delivery carries one signature per active secret.
Rotation creates a new secret and keeps the old one valid for a while, so you can switch without losing a call. The new secret is also shown only once.
Idempotency and retries
Your server must answer with a 2xx status. Otherwise the delivery is retried several times, at growing intervals, then abandoned. The documentation gives the retry schedule and remains the reference.
Retries mean your server can receive the same event twice, for example when it processed the call but answered too late. The X-Event-Id header is identical on every retry of the same event. Record it, and ignore an identifier you have already processed.
- Answer fast. Check the signature, store the event, return 200, and do slow work afterwards.
- Do not assume order. Make each handler safe on its own: a proof.sealed for a booking you already marked as sealed changes nothing.
- Keep a fallback. If an event was abandoned, read the proof with your key: the API stays the source of truth.
The delivery log shows what was sent and what your server answered. List it with GET /v1/webhook-deliveries and filter by status, for example abandoned, to find the events your server never accepted. A single delivery returns the JSON payload exactly as your endpoint received it, which you can replay on your own server.
Example integration: attaching proofs to bookings
Take a rental platform. A capture session is created at pickup with the booking number as external_reference.
When the proof is sealed, the booking page must show the verification link. Our article on vehicle rental damage proof describes the business side of this flow.
This receiver uses Node.js alone and the isValid function above. The attachProof function stands for your own code.
import { createServer } from 'node:http';
const seen = new Set(); // in production: a table with a unique index
createServer(async (req, res) => {
const chunks = [];
for await (const chunk of req) chunks.push(chunk);
const rawBody = Buffer.concat(chunks).toString('utf8');
const signature = req.headers['x-signature'] ?? '';
if (!isValid(signature, rawBody, process.env.WEBHOOK_SECRET)) {
res.writeHead(400).end();
return;
}
const eventId = req.headers['x-event-id'];
if (seen.has(eventId)) {
res.writeHead(200).end(); // duplicate: already processed
return;
}
seen.add(eventId);
const body = JSON.parse(rawBody);
if (body.event === 'proof.sealed' && !body.test) {
await attachProof(body.external_reference, body.proof_id, body.verify_url);
}
res.writeHead(200).end();
}).listen(3000);To try it, send yourself an example event with POST /v1/webhook-endpoints/<id>/test and the event_type you want. The body has the same fields as a real event, with example values and a test field set to true. It is signed with your secret like any delivery, so your signature code is tested end to end.
You can also explore the endpoints by hand before writing code: the Postman setup imports every call from the OpenAPI schema. Once proofs reach your back office, a third party may want to check one alone. That is the subject of verifying a sealed photo programmatically.
Frequently asked questions
How are webhook signatures computed?
With HMAC-SHA256. The signed string is the timestamp t from the X-Signature header, a dot, then the raw body of the request. The key is the secret of your endpoint, the whole string including its whsec_ prefix, and the result is written in lowercase hexadecimal. Reject any call whose timestamp is too old.
What happens if my server is down?
The delivery is retried. Without a 2xx answer, the service tries again several times, at growing intervals, then gives up and marks the delivery as abandoned. You can list abandoned deliveries, read the exact payload that was sent, and replay it on your own server once it is back.
Can I receive the same event twice?
Yes, and your handler should expect it. A retry carries the same X-Event-Id header as the first attempt, while X-Webhook-Id changes with each attempt. Store the event identifier with a unique constraint and skip any event you have already processed. Your handler then gives the same result however many times it is called.
Should I wait for capture_session.completed or proof.sealed?
Both, for different purposes. capture_session.completed is the reliable signal that the person has finished, since they may close the page before being taken back to your app. The proof is not sealed at that point. Wait for proof.sealed before you show a verification link or rely on the proof.
Can I test webhooks without a real capture?
Yes. A test call sends an example event to your endpoint, signed with your secret, with a test field set to true. It appears in the delivery log, and the number of test events per hour is limited. Your handler should skip the events that carry this flag, as the example in this article does.
Try it in the sandbox
Photo evidence webhooks keep your back office in step with what happens on a phone: one signed call when a proof is sealed, a stable identifier to ignore duplicates, and a log to replay what was missed. You can declare an endpoint and receive your first signed events for free in the sandbox, without a card.
Create an accountOfficial sources
Cédric Driaux · Founder of tryVidimus
Cédric Driaux is the founder of tryVidimus, published by Fyher. He has been a software developer for 23 years. He also builds ScanStay, a photo proof tool for short-term rental hosts.