Gå til indhold

Webhooks

Med webhooks sender ownr en HTTP POST til jeres server, når der sker en ændring. I slipper for at spørge API’et igen og igen.

Opsætning

  1. Opret et HTTPS-endpoint på jeres server, der tager imod POST med JSON.
  2. Tilføj adressen som webhook-endpoint under API Adgang.
  3. Svar med en 2XX-status inden for 20 sekunder, når I modtager en hændelse.

ownr sender en webhook, når noget ændrer sig på en virksomhed, en erhvervsperson eller en ejendom i jeres Ajour-liste, og når emner kommer ind i eller går ud af et segment, I abonnerer på. Emner, du følger, giver notifikationer i ownr, ikke webhooks.

Alle hændelser sendes til hvert webhook-endpoint, virksomheden har tilføjet. Felterne event og data.field i kroppen fortæller, hvilken hændelse det er. Webhook-leveringer tæller ikke i API-kvoten.

Eksempel på en hændelse

company/changed-name sendes, når en virksomhed skifter navn:

{
"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"
}
}

Alle hændelser og deres felter står under Hændelser.

Bekræft afsenderen

Hvert kald har headeren X-Secret med en fast værdi, I selv vælger under API Adgang. Den er ikke en signatur: den beskytter ikke indholdet og kan ikke afsløre et genafspillet kald.

Vi anbefaler derfor HMAC-signering, som I slår til under API Adgang (Sign requests with HMAC-SHA256). Nye virksomheder har det slået til fra start. Så har hvert kald også headeren:

X-Ownr-Signature: t=1759830000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t er afsendelsestidspunktet som unix-tid.
  • v1 er HMAC-SHA256(signing_secret, "<t>.<rå krop>") som hex.
  • signing_secret begynder med whsec_ og vises én gang under API Adgang.

Sådan bekræfter I et kald:

  1. Beregn HMAC’en over de nøjagtige bytes i den modtagne krop, med t fra headeren.
  2. Sammenlign med alle v1-værdier i headeren med en konstant-tids-sammenligning.
  3. Afvis kaldet, hvis ingen matcher, eller hvis t ligger mere end få minutter fra nu.
Node.js
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)),
);
}
# Python
import 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)

Når I fornyer signeringsnøglen, indeholder headeren to v1-værdier i 24 timer: én med den nye nøgle og én med den gamle. Så kan I skifte uden nedetid.

Levering

  • Hændelser sendes én ad gangen, cirka én pr. sekund.
  • En levering fejler ved netværksfejl eller et svar uden for 2XX. Den prøves igen ved næste kørsel, hvert 15. minut, op til 3 forsøg i alt.
  • Alle forsøg på samme hændelse har samme event_id. Brug det til at springe hændelser over, I allerede har behandlet.
  • Et endpoint sættes på pause efter 50 fejlede leveringer i træk eller 3 dage med fejl.
  • I leveringsloggen kan I se hvert kald og jeres servers svar.

Hændelser

Der er 51 hændelser. Hver side viser, hvornår hændelsen sendes, et eksempel og alle felter i kroppen.

Gruppe Antal Gælder
Virksomheder 26 Virksomheder i Ajour
Erhvervspersoner 16 Erhvervspersoner i Ajour
Ejendomme 6 Ejendomme i Ajour
Segmenter 3 Segmenter, I abonnerer på