Webhooks
With webhooks, ownr sends an HTTP POST to your server when a change happens. You no longer have to poll the API.
Setup
- Create an HTTPS endpoint on your server that accepts POST with JSON.
- Add its address as a webhook endpoint under API Adgang.
- Answer with a
2XXstatus within 20 seconds when you receive an event.
ownr sends a webhook when something changes on a company, person or property in your Ajour list, and when items enter or leave a segment you subscribe to. Items you follow give notifications in ownr, not webhooks.
Every event is sent to each webhook endpoint your organisation has added. The fields event and data.field in the body tell the events apart. Webhook deliveries do not count against the API quota.
Example event
company/changed-name is sent when a company changes its name:
{ "event": "company.updated", "event_id": "req_63246e166IstnPKY", "data": { "field": "name", "date": "2022-10-01", "item": { "id": 36732261, "slug": "company", "url": "/api/v2/company/36732261", "name": "SNT ApS new name" }, "name": "SNT ApS new name", "original_name": "SNT ApS" }}Every event and its fields are listed under Events.
Verify the sender
Every request carries the header X-Secret with a static value you set under API Adgang. It is not a signature: it does not protect the body and cannot detect a replayed request.
We therefore recommend HMAC signing, which you turn on under API Adgang (Sign requests with HMAC-SHA256). New organisations have it on from the start. Every request then also carries:
X-Ownr-Signature: t=1759830000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdtis the delivery time as unix time.v1isHMAC-SHA256(signing_secret, "<t>.<raw body>")in hex.signing_secretstarts withwhsec_and is shown once under API Adgang.
To verify a request:
- Compute the HMAC over the exact bytes of the body received, with the
tfrom the header. - Compare it with every
v1value in the header, using a constant-time comparison. - Reject the request if none match, or if
tis more than a few minutes from now.
import crypto from 'node:crypto';
function isFromOwnr(rawBody, signatureHeader, signingSecret) { const parts = signatureHeader.split(',').map((p) => p.split('=')); const t = parts.find(([k]) => k === 't')?.[1]; const signatures = parts.filter(([k]) => k === 'v1').map(([, v]) => v); if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto .createHmac('sha256', signingSecret) .update(`${t}.${rawBody}`) .digest('hex');
return signatures.some( (s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)), );}# Pythonimport hashlib, hmac, time
def is_from_ownr(raw_body: bytes, signature_header: str, signing_secret: str) -> bool: parts = [p.split("=", 1) for p in signature_header.split(",")] t = next((v for k, v in parts if k == "t"), None) signatures = [v for k, v in parts if k == "v1"] if t is None or abs(time.time() - int(t)) > 300: return False expected = hmac.new( signing_secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256 ).hexdigest() return any(hmac.compare_digest(s, expected) for s in signatures)When you rotate the signing secret, the header carries two v1 values for 24 hours: one signed with the new secret and one with the old. That lets you switch without downtime.
Delivery
- Events are sent one at a time, about one per second.
- A delivery fails on a network error or an answer outside
2XX. It is tried again on the next run, every 15 minutes, up to 3 attempts in all. - Every attempt of the same event carries the same
event_id. Use it to skip events you have already handled. - An endpoint is paused after 50 failed deliveries in a row or 3 days of failing.
- The delivery log shows each request and your server’s answer.
Events
There are 51 events. Each page shows when the event is sent, an example and every field in the body.
| Group | Count | Applies to |
|---|---|---|
| Companies | 26 | Companies in Ajour |
| Persons | 16 | Persons in Ajour |
| Properties | 6 | Properties in Ajour |
| Segments | 3 | Segments you subscribe to |