Webhooks

Generell HTTPS-webhook for å sende Orakel-data til et hvilket som helst eget system.

Oversikt

Destinasjonstypen webhook sender Orakel-data med POST til en adresse du oppgir. Bruk den når det ikke finnes en egen kobling for systemet ditt, eller når du vil ha dataene i rå form.

Hver push er én HTTPS-forespørsel. Kroppen inneholder alle bedriftene som ble hentet, med regnskapstall, roller, underenheter og bevillinger vedlagt.

Oppsett

Opprett en destinasjon av typen webhook:

curl -X POST https://orakel.cloud/api/destinations \
  -H "Authorization: Bearer $ORAKEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-webhook",
    "type": "webhook",
    "config": {
      "url": "https://ingest.example.com/orakel",
      "method": "POST",
      "headers": { "X-Tenant": "acme" }
    }
  }'

Start en push:

curl -X POST https://orakel.cloud/api/push/my-webhook \
  -H "Authorization: Bearer $ORAKEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orgNumbers": ["923609016","912345678"]}'

Formen på kroppen

Én POST per push-kall. Kroppen samler alle bedriftene i én companies-liste:

{
  "companies": [
    {
      "id": "...",
      "orgNumber": "923609016",
      "country": "NO",
      "name": "Equinor ASA",
      "orgFormCode": "ASA",
      "naceCode1": "06.100",
      "naceDescription1": "Utvinning av raolje",
      "employeeCount": 21000,
      "businessAddressStreet": "...",
      "primaryDomain": "equinor.com",
      "enrichedDomains": ["equinor.com"],
      "technologies": [{ "name": "...", "category": "...", "confidence": 0.9 }],
      "financials": [{ "periodTo": "2024-12-31", "revenue": 1000000000, "netResult": 100000000 }],
      "roles": [{ "roleTypeCode": "DAGL", "personFirstName": "...", "personLastName": "..." }],
      "subUnits": [{ "orgNumber": "...", "name": "..." }],
      "licenses": [{ "licenseTypeCode": "01SKJE", "venueName": "..." }]
    }
  ]
}

Formen følger Prisma-modellen Company med financials, roles, subUnits og licenses inkludert. Typen CompanyWithRelations i lib/push/adapters/types.ts er fasiten.

Konfigurasjon

Felt	Type	Påkrevd	Beskrivelse
`url`	tekst	ja	HTTPS-adresse.
`method`	tekst	nei	Standard er `POST`.
`headers`	objekt	nei	Ekstra hoder, slått sammen med `Content-Type: application/json`.

{
  "url": "https://ingest.example.com/orakel",
  "method": "POST",
  "headers": {
    "X-Tenant": "acme",
    "Authorization": "Bearer ..."
  }
}

Konfigurasjonen krypteres (AES-256-GCM).

Sikkerhet

Bruk alltid HTTPS. Orakel legger ingen hemmeligheter i kroppen, men token du setter i headers følger hver forespørsel.
Delt hemmelighet: legg autentiseringstokenet ditt i et eget hode med config.headers. Mottakeren sjekker det.
Signatur: dagens webhook signerer ikke kroppen. Trenger du HMAC-signering, bruk en egen kobling eller sett en signerende proxy foran mottakeren.
IP-tillatelsesliste: Orakel kaller ut fra Hetzner i Helsinki. Ta kontakt på hello@orakel.cloud for gjeldende IP-område.

Hvordan push fungerer

Én POST per kall til POST /api/push/:destinationName, uansett hvor mange organisasjonsnumre du sender.
Svarer mottakeren noe annet enn 2xx, merkes hele bunken som mislykket og returneres i errors[].
Nettverksfeil eller tidsavbrudd behandles likt: hele bunken feiler.
Ingen gjentatte forsøk, ingen økende ventetid. Den som kaller, prøver på nytt ved å kalle /api/push/:destinationName igjen.
Grenser på mottakersiden er mottakerens ansvar. Bunkene begrenses av push-endepunktets grense på 100 organisasjonsnumre.

Verdt å vite

Alt eller ingenting. Ett svar utenfor 2xx feller hele pushen. Del store bunker i mindre hvis mottakeren er ustabil.
Ingen innebygd duplikatsjekk. Sender du det samme organisasjonsnummeret to ganger, blir det to forespørsler. Bruk orgNumber som nøkkel på mottakersiden.
X-Forwarded-*: står mottakeren bak en proxy og du sjekker en signatur selv, må du bygge opp den offentlige adressen før du hasher. Orakel sender direkte, men interne mottakere gjør sjelden det.
TLS kreves. Vanlige HTTP-adresser godtas ved oppsett, men bør ikke brukes. Ingen garantier for hva mellomledd gjør.
Størrelse på kroppen: hver bedrift bærer regnskapstall, roller, underenheter og bevillinger. En push med 100 bedrifter kan bli flere hundre kilobyte.

Se også

Destinasjoner: endepunkter for destinasjoner og for å utløse push
Attio: egen kobling som slår sammen oppføringer
HubSpot: egen kobling med OAuth og berikelse via webhook

På denne siden