Webhookit

Rakenna ja varmenna ensin vastaanotin, rekisteröi sitten sen julkinen HTTPS-osoite, luo vahti ja varmista testin toimitus. Rekisteröinti, jonotus ja toimitus ovat eri lopputuloksia. Käytä alla olevia palautumis- ja vaihto-ohjeita olemassa olevan tilauksen ylläpitoon.

Käytä tuotantoavainta, jolla on webhooks:write-oikeus ja tilauksen webhooks:manage-käyttöoikeus. Vain julkiset HTTPS-osoitteet portissa 443 hyväksytään. Tallenna vastauksen salaisuus turvallisesti: listaus ei paljasta sitä. Testiavainten tilaukset ovat erillisiä eivätkä lähetä verkkotoimituksia.

curl --fail-with-body https://hintadata.fi/v1/webhooks \
  -H "Authorization: Bearer $HINTADATA_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: endpoint-create-001' \
  -d '{"url":"https://receiver.example/events","events":["watchlist.triggered"]}'

Luo vahti channel=webhook-arvolla ilman sähköpostiosoitetta. Uusi lähdeaineisto, jossa aktiivinen vahti siirtyy tavoitehinnan alle, jonottaa watchlist.triggered-tapahtuman työtilan kaikille aktiivisille vastaaville tilauksille. Rekisteröinti ei toimita vanhoja tapahtumia. Sähköpostivahdit käyttävät edelleen erillistä operaattorin sähköpostisiltaa.

{"canonical_product_id":"sony_wh1000xm5_black","condition":"target_price","target_price":250,"channel":"webhook"}

Lähetä runko POST-pyynnöllä osoitteeseen /v1/watchlists käyttäen watchlists:write-oikeutta ja uutta Idempotency-Key-avainta. Tuotannon lähdeaineiston on oltava jo saatavilla. delivery_unavailable tarkoittaa, ettei operaattori ole määrittänyt toimituskanavaa.

Dashboard käyttää samoja tilauksia kuin API. Muokkaa HTTPS-kohdetta ja tapahtumasuodatuksia, keskeytä/jatka, vaihda allekirjoitussalaisuus ja tarkastele sivutettua historiaa, mittareita ja auditointia. GET /v1/webhook-metrics koostaa säilytetyt toimitukset; GET /v1/webhook-audit palauttaa 100 uusinta hallintatapahtumaa (enintään 1 000 säilyy 30 päivää). Toimijat ovat yksisuuntaisia tunnisteita, eivät tunnuksia. last_error_code erottaa HTTP-, DNS-, TLS-, aikakatkaisu-, siirto-, salaus- ja lähteen voimassaolovirheet paljastamatta vastausrunkoja.

POST /v1/webhooks/{id}/test rungolla {"confirm":true} ja Idempotency-Key-avaimella jonottaa nimenomaisesti live-webhook.test-tapahtuman, jossa on vain {"test":true}. Se ei sisällä asiakasdataa; aktiiviseen päätepisteeseen voi jonottaa yhden testin minuutissa. Työntekijä lähettää myöhemmin; jonotusvastaus ei todista toimitusta. Testiympäristön API-avaimet eivät koskaan lähetä. Tarkista ja deduplikoi testit kuten muut tapahtumat, mutta älä tee liiketoimintamuutoksia.

Lue GET /v1/webhook-deliveries?subscription_id={id}&limit=25, jatka tarvittaessa next_offset-arvosta ja etsi palautettu toimitustunniste. Onnistuminen edellyttää delivered-tilaa ja vastaanottajan kirjausta; pending tai sending ei ole valmis. Jos tila on failed, noudata alla olevaa toimituksen vianmääritystä ennen uusintapyyntöä.

POST /v1/webhook-deliveries/{id}/retry uudella Idempotency-Key-avaimella pyytää epäonnistuneen toimituksen auditoitua uusintaa. Lähdeaineiston on oltava edelleen voimassa, päätepisteen aktiivinen ja osoitteen/suodatusten ennallaan. Alkuperäiset tapahtuma- ja toimitustunnisteet säilyvät. Enintään kolme manuaalista uusintaa seitsemässä päivässä, kahdeksan yritystä kierroksessa (yhteensä 32). Peruttuja tai vanhentuneita havaintoja ei voi elvyttää. Toista epävarma pyyntö samalla avaimella; älä poista vastaanottajan duplikaattisuojausta.

Tarkista X-Webhook-Signature täsmälleen vastaanotetusta rungosta: t=<sekunnit>,v1=<hex HMAC-SHA256(salaisuus, aikaleima + "." + runko)>. Hylkää yli viiden minuutin aikaero. Estä tämän jälkeen duplikaatit tapahtuman event.id- / Idempotency-Key-tunnisteella samassa transaktiossa oman muutoksesi kanssa. Toimitus voi toistua eikä järjestystä taata. Älä tarkista allekirjoitusta uudelleen sarjoitetusta JSONista.

import { verifyWebhook } from '@pricecompare/sdk';
const event = await verifyWebhook(rawBody, signatureHeader, signingSecret);
// Persist event.id and your business effect atomically before returning 2xx.

from price_compare.webhooks import verify_webhook
event = verify_webhook(raw_body_bytes, signature_header, signing_secret)
# Persist event["id"] and your business effect atomically before returning 2xx.

GET /v1/webhook-deliveries?limit=25 palauttaa toimitukset tiloissa pending, sending, delivered, failed tai cancelled. Rajaa subscription_id-arvolla ja jatka next_offset-arvosta. attempt_history näyttää yrityksen alku- ja loppuajan, keston, turvallisen virhekoodin, HTTP-tilan ja seuraavan yrityksen ilman runkoja tai salaisuuksia. Mikä tahansa 2xx kuittaa. HTTP 4xx on pysyvä virhe lukuun ottamatta koodeja 408, 409, 425 ja 429; myös estetty kohde on pysyvä virhe. Muita virheitä yritetään enintään kahdeksan kertaa kierroksessa satunnaistetulla kasvavalla viiveellä ja enintään tunnin Retry-After-ajalla. Kolme peräkkäistä tilapäisvirhettä keskeyttää vastaanottajan viideksi minuutiksi, pysyvä virhe 15 minuutiksi. Jäähyn jälkeen sallitaan yksi koeyritys. Työntekijän ajastus voi pidentää viivettä. Historia säilyy seitsemän päivää.

Vastaanottajan häiriöt ovat erillisiä toimitushistoriasta. POST /v1/webhooks/{id}/incidents/acknowledge rungolla {"incident_id":"wi_..."} ja uudella Idempotency-Key-avaimella lopettaa muistutukset piilottamatta ratkaisematonta häiriötä tai peruuttamatta uusintayrityksiä. Korjaa vastaanottaja ja lähetä testi tai uusi voimassa oleva epäonnistunut toimitus. Onnistunut toimitus ratkaisee häiriön ja käynnistää palautumisilmoituksen; vanhat virheet jäävät näkyviin. Kuittaus ei yksin tarkoita palautumista.

PATCH /v1/webhooks/{id} rungolla {"enabled":false} keskeyttää; DELETE poistaa. Kohteen tai suodattimen muutos peruu jonossa olevat toimitukset. Osoitteen vaihto tai nimenomainen jatkaminen nollaa jäähyn. Lähteen version muutos tai vanheneminen peruu lähettämättömät havainnot; jo matkalla olevaa pyyntöä ei voi perua.

POST /v1/webhooks/{id}/secret-rotation uudella Idempotency-Key-avaimella valmistelee salaisuuden 24 tunniksi muuttamatta allekirjoitusta. Asenna se vastaanottajalle nykyisen rinnalle. Kutsu sitten POST /v1/webhooks/{id}/secret-rotation/activate rungolla {"rotation_id":"wr_...","confirm":true} ja eri Idempotency-Key-avaimella. Allekirjoitus vaihtuu atomisesti. Hyväksy vanha salaisuus vähintään 60 sekuntia jo matkalla olevia pyyntöjä varten ja poista se sitten vastaanottajalta. Valmistelun voi perua kutsulla POST /v1/webhooks/{id}/secret-rotation/cancel ja rungolla {"rotation_id":"wr_..."}. Luonti ja valmistelu palauttavat alkuperäisen salaisuusvastauksen uusinnassa 24 tuntia; listaus, aktivointi ja peruminen eivät paljasta salaisuuksia. API-sopimus 2.0.0 poistaa vanhan välittömän vaihtotoiminnon.