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
- Opret et HTTPS-endpoint på jeres server, der tager imod POST med JSON.
- Tilføj adressen som webhook-endpoint under API Adgang.
- 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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdter afsendelsestidspunktet som unix-tid.v1erHMAC-SHA256(signing_secret, "<t>.<rå krop>")som hex.signing_secretbegynder medwhsec_og vises én gang under API Adgang.
Sådan bekræfter I et kald:
- Beregn HMAC’en over de nøjagtige bytes i den modtagne krop, med
tfra headeren. - Sammenlign med alle
v1-værdier i headeren med en konstant-tids-sammenligning. - Afvis kaldet, hvis ingen matcher, eller hvis
tligger mere end få minutter fra nu.
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)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å |