Vastaanota tapahtumat webhookeilla

Teams-paketista alkaen

Teams-paketista alkaen lähetämme allekirjoitetun JSON-tapahtuman HTTPS-päätepisteeseesi, kun tallennamme raportin, kun hälytys avautuu tai poistuu ja kun API:n kautta aloitettu vienti on valmis. Vastaanottajasi tarkistaa allekirjoituksen, vastaa 2xx-tilalla ja tekee vasta sitten oman työnsä.

Lisää päätepiste

Ylläpitäjä lisää päätepisteet kohdassa Asetukset → Kehittäjille → Webhookit. Paketti määrää, montako niitä voi olla:

Paketti	Päätepisteitä
Starter	0
Pro	0
Teams	10
Enterprise	25

Kirjoita kuvaus, esimerkiksi tapahtumat vastaanottavan järjestelmän nimi.
Anna päätepisteen URL-osoite: julkisessa internetissä oleva https://-osoite, jossa on palvelimen nimi eikä IP-osoite ja jossa ei ole käyttäjänimeä.
Valitse tapahtumat, jotka päätepiste saa. Aluksi kaikki on valittu.
Paina Lisää päätepiste.

Seuraava sivu näyttää päätepisteen allekirjoitussalaisuuden vain kerran. Salaisuus alkaa merkeillä whsec_. Lisää se vastaanottajasi asetuksiin ja paina sitten päätepisteen sivulla Lähetä testi. Testitapahtuma webhook.test menee vain tähän päätepisteeseen. Yritämme lähettää sen kerran emmekä yritä uudelleen.

Päätepiste saa jokaisen sille valitun tapahtuman organisaation jokaisesta verkkotunnuksesta.

Tapahtumat

Tapahtuma	Milloin lähetämme sen	Data-objektin kentät
`report.received`	Tallensimme koonti-, TLS- tai forensic-raportin jollekin organisaation verkkotunnukselle. Forensic-raportista kerrotaan vain tunnisteet, ei koskaan sisältöä.	`id` `kind` `domain` `reporter` `report_id` `begin` `end` `received_at` `counts` `url` `raw_url`
`alert.fired`	Hälytys avautui tai tapahtui jotain, mistä hälytykset kertovat.	`id` `domain` `subject` `kind` `severity` `fired_at` `resolved_at` `headline` `text` `action` `params` `url`
`alert.resolved`	Avoin hälytys poistui. Sen tunniste on sama kuin alert.fired-tapahtuman.	`id` `domain` `subject` `kind` `severity` `fired_at` `resolved_at` `headline` `text` `action` `params` `url`
`export.ready`	API:n kautta aloitettu vienti on valmis ladattavaksi.	`id` `kind` `status` `domain` `from` `to` `header_from` `report_kinds` `created_at` `expires_at` `size_bytes` `download_url`
`webhook.test`	Lähtee yhdelle päätepisteelle, kun ylläpitäjä painaa Lähetä testi -painiketta.	`organization` `endpoint`

Jokaisen tapahtuman runko on samanlainen:

{
  "type": "export.ready",
  "timestamp": "2026-10-27T07:41:12Z",
  "data": { … }
}

type nimeää tapahtuman, timestamp kertoo UTC-aikana, milloin loimme sen, ja data sisältää taulukon kentät. OpenAPI-dokumentti kuvaa kunkin tapahtuman data-kentän kokonaan kohdassa webhooks, ja pyyntöjen luettelo kertoo, mistä dokumentin löydät.

Tarkista allekirjoitus

Jokaisessa POST-pyynnössä on kolme otsaketta, jotka on allekirjoitettu Standard Webhooks -tavalla:

webhook-id: tapahtuman tunniste, esimerkiksi msg_1234. Tapahtuman jokaisessa uudelleenyrityksessä on sama tunniste.
webhook-timestamp: tämän yrityksen hetki Unix-sekunteina.
webhook-signature: v1, ja sen perässä HMAC-SHA256-allekirjoitus base64-muodossa. Salaisuuden vaihdon jälkeen siinä on jonkin aikaa kaksi allekirjoitusta välilyönnillä erotettuina.

Allekirjoitus kattaa tunnisteen, aikaleiman ja rungon pisteillä yhdistettyinä. Sen avain on salaisuus ilman alkua whsec_ base64-muodosta purettuna. Mikä tahansa Standard Webhooks -kirjasto tarkistaa sen. Ilman kirjastoa tämä Python-koodi tekee saman standardikirjastolla:

import base64
import hashlib
import hmac
import time


def verify(secret: str, headers: dict, body: bytes, tolerance: int = 300) -> bool:
    """True when a signature matches and the timestamp is recent."""
    msg_id = headers.get("webhook-id", "")
    timestamp = headers.get("webhook-timestamp", "")
    signatures = headers.get("webhook-signature", "")
    if not (msg_id and timestamp and signatures):
        return False
    try:
        sent_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - sent_at) > tolerance:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = msg_id.encode() + b"." + timestamp.encode() + b"." + body
    digest = hmac.new(key, signed, hashlib.sha256).digest()
    expected = base64.b64encode(digest).decode()
    for signature in signatures.split():
        version, _, value = signature.partition(",")
        if version == "v1" and hmac.compare_digest(value.encode(), expected.encode()):
            return True
    return False

Anna funktiolle pyynnön käsittelemätön runko tavuina ennen JSON-jäsennystä, koska allekirjoitus kattaa juuri ne tavut. Anna otsakkeet sellaisina kuin verkkokehyksesi ne antaa, tai niin, että niiden nimet ovat pienillä kirjaimilla. Hylkää POST-pyyntö, kun funktio palauttaa False. Esimerkki hylkää myös aikaleiman, joka poikkeaa kellostasi yli tolerance sekuntia, joten tallennettua pyyntöä ei voi lähettää sinulle myöhemmin uudelleen.

Vastaa nopeasti

Vastaa millä tahansa 2xx-tilalla 5 sekunnin kuluessa. Kaikki muu lasketaan epäonnistumiseksi: muu tila, vastaus, joka ei ehdi ajoissa, tai uudelleenohjaus, jota emme seuraa. Tee hidas työ vasta vastattuasi.

Tapahtumat voivat saapua väärässä järjestyksessä, ja uudelleenyritys voi saapua uudemman tapahtuman jälkeen. Järjestä ne timestamp-kentän mukaan.
Poista kaksoiskappaleet webhook-id-otsakkeen avulla.

Kun toimitus epäonnistuu

Epäonnistuneen yrityksen jälkeen odotamme ja yritämme uudelleen. Odotusajat ovat järjestyksessä 1 minuutti, 10 minuuttia, 1 tunti, 6 tuntia ja 24 tuntia. Jos viimeinenkin yritys epäonnistuu, toimitus merkitään epäonnistuneeksi, emmekä yritä enää.

Päätepisteen sivulla on Toimitusloki. Siinä näkyy jokainen tapahtuma, jonka lähetimme tai yritimme lähettää päätepisteeseen, sekä vastaanottajasi palauttama tila ja virhe. Lokin aikaväli on 90 päivää.

Kun kaikki toimitukset päätepisteeseen ovat epäonnistuneet jo 3 päivää, poistamme päätepisteen käytöstä ja lähetämme ylläpitäjille sähköpostia. Tapahtumia ajalta, jolloin päätepiste on poissa käytöstä, ei lähetetä koskaan. Korjaa vastaanottaja ja paina sitten päätepisteen sivulla Ota käyttöön.

Vaihda salaisuus

Kun painat päätepisteen sivulla Vaihda salaisuus, saat heti uuden salaisuuden, ja sivu näyttää sen kerran. Vanha salaisuus toimii vielä 24 tuntia. Sinä aikana jokaisessa POST-pyynnössä on kaksi allekirjoitusta, yksi kummallekin salaisuudelle, ja kumpi tahansa riittää. Vaihda uusi salaisuus vastaanottajasi asetuksiin, ennen kuin aika loppuu. Jos vaihdat salaisuuden uudelleen sinä aikana, vanhin salaisuus lakkaa toimimasta.

Kun paketti vaihtuu

Paketti, jossa on vähemmän päätepisteitä. Vanhimmat päätepisteet saavat tapahtumia uuden paketin sallimaan määrään asti, ja uudemmat keskeytetään. Keskeytetty päätepiste saa tapahtumia taas, kun vanhempi päätepiste otetaan pois käytöstä tai poistetaan tai kun paketti sisältää enemmän päätepisteitä.
Paketti ilman webhookeja. Lopetamme lähettämisen, ja uudelleenyritystä odottavat tapahtumat jätetään lähettämättä. Säilytämme päätepisteet ja niiden salaisuudet. Ne toimivat taas samoilla salaisuuksilla, kun organisaatiolla on jälleen Teams-paketti tai sitä parempi.

Päätepiste vai hälytyskanava?

Hälytykset voi lähettää myös webhook-kanavaan kohdassa Asetukset → Ilmoitukset, Teams-paketista alkaen. Kanava lähettää vain ne hälytykset, jotka valitset hälytystyypeittäin. Sen tapahtumat ovat alert.opened, alert.resolved ja alert.test, ja ne allekirjoitetaan samalla tavalla. Avautuvan hälytyksen tapahtuma on siis päätepisteessä alert.fired ja kanavassa alert.opened. Päätepiste saa jokaisen valitsemasi tapahtuman jokaisesta verkkotunnuksesta, myös raportit ja viennit.

Julkaistu 27. lokakuuta 2026 · Tarkistettu 27. lokakuuta 2026