Webhooks
Have expiration item events delivered to your own endpoint the moment they happen — signed, filtered to the events you care about, and with full change details.
Push instead of polling
Instead of periodically asking the API whether anything changed, Validarium sends an HTTP POST to your endpoint whenever an event is recorded in an expiration item's history. Every workspace member can create webhooks in the web app under Settings → Webhooks: choose a name, the endpoint URL, and optionally the event types to subscribe to. Members manage their own webhooks; the workspace owner sees them all.
What triggers a delivery
A webhook fires for events across the entire workspace — including changes made by other members. Leave the subscription empty to receive everything, or pick specific types.
created
An expiration item was created.
updated
An item was edited; the payload lists each changed field with its previous and new value.
expiration_date_changed
The expiration date changed; the payload carries the old and new date.
renewed
The item was renewed with a new validity date.
archived
The item was moved to the archive.
restored
The item was restored from the archive.
deleted
The item was deleted.
attachment_uploaded
An attachment was uploaded; the payload carries the file name.
attachment_deleted
An attachment was removed; the payload carries the file name.
reminder_changed
Reminders of the item were changed.
What your endpoint receives
Each delivery is a JSON POST with the event type, the workspace, the item, event details, and the member who made the change:
{
"event": "expiration_date_changed",
"occurred_at": "2026-07-18T09:30:00+00:00",
"workspace": {
"id": 1,
"uuid": "9d3f4c3e-...",
"name": "Family workspace"
},
"item": {
"uuid": "8b2a1f6d-...",
"name": "Passport",
"expires_at": "2027-05-01"
},
"payload": {
"old_expires_at": "2026-05-01",
"new_expires_at": "2027-05-01"
},
"user": {
"id": 7,
"name": "Pavel"
}
}Verifying the signature
Every delivery is signed with the webhook's secret using HMAC-SHA256. The secret is shown once when the webhook is created and can be regenerated at any time. Compare the X-Validarium-Signature header with your own digest of the raw request body:
$expected = 'sha256='.hash_hmac('sha256', $request->getContent(), $secret);
abort_unless(
hash_equals($expected, (string) $request->header('X-Validarium-Signature')),
401,
);Delivery headers
- X-Validarium-Signature
- HMAC-SHA256 digest of the request body, prefixed with "sha256=".
- X-Validarium-Event
- The event type, useful for routing without parsing the body.
- X-Validarium-Webhook-Id
- The webhook id, useful when one endpoint serves several webhooks.
Delivery and retries
Deliveries are queued and asynchronous, so they never slow the app down. If your endpoint does not respond with a success status, Validarium retries up to three times with increasing delays (10 s, 60 s, 180 s). A webhook can be deactivated at any time without deleting it.
Web and cloud only
Webhooks run on the server, so they cover the web app and the mobile Cloud mode. Device mode never touches the server, so purely local changes do not trigger webhooks — consistent with device data never leaving the phone.
Typical uses
Team notifications
Forward events to Slack, Teams, or Discord — directly or through tools like Zapier, Make, or n8n.
System synchronization
Keep an ERP, CRM, or internal database up to date with renewals and date changes in real time.
Automation and audit
Create follow-up tasks on renewal, build independent audit logs, or feed custom dashboards without polling.