Webhookit

GRYPHEM PAY lähettää HTTPS-POST-pyynnön rekisteröimiisi päätepisteisiin aina, kun tilaamasi asia tapahtuu. Toimitukset ovat allekirjoitettuja, ne tapahtuvat vähintään kerran (at-least-once) ja niitä yritetään uudelleen viiveellä — siksi vastaanottimesi täytyy todentaa, ohittaa kaksoiskappaleet ja kuitata nopeasti.

Rekisteröi päätepiste

POST/v1/webhook-endpointslive · tilin aktivoinnin jälkeen

{
  "url": "https://merchant.example/webhooks/gryphem",
  "enabled_events": ["payment.confirmed", "payment.review_required", "payment.reorged", "payment.expired"],
  "description": "Order fulfilment"
}

Vastaus sisältää allekirjoitussalaisuuden secret (whsec_…) vain kerran. Käytä arvoa ["*"] saadaksesi kaikki tapahtumatyypit. Päätepisteet ovat ympäristökohtaisia, ja ne voi halutessaan rajata yhteen kauppaan. Live-tapahtumat toimitetaan vain live-tilassa rekisteröityihin päätepisteisiin, joten rekisteröi omasi, kun tilisi on aktivoitu.

URL-osoitteiden on oltava julkisia HTTPS-osoitteita. Ne tarkistetaan rekisteröinnissä ja uudelleen toimitushetkellä: kohteen IP-osoite tarkistetaan yhteyttä muodostettaessa (yksityiset, loopback-, link-local- ja metatieto-osoitteet torjutaan), uudelleenohjauksia ei seurata ja koot sekä aikakatkaisut on rajattu. Paikallisessa kehityksessä yksityinen osoite kuten http://localhost:4400 toimii vain, jos alustan ylläpitäjä on ottanut käyttöön erillisen kehitysasetuksen.

Tapahtumat

`event_type`	Lähetetään, kun
`payment_intent.created`	Aikomus luodaan (API, hallintapaneeli, lasku tai maksulinkki)
`invoice.awaiting_payment`	Laskun aikomuksella on lukittu tarjous ja osoite
`payment.detected`	Siirto on havaittu, mutta se ei ole lopullinen
`payment.confirming`	Siirto on lohkossa ja kerää vahvistuksia
`payment.confirmed`	Odotettu summa on lopullinen — tarkista `data.fulfillable`
`payment.expired`	Tarjous vanheni ilman maksua
`payment.review_required`	`underpaid`, `overpaid`, `late_payment`, `manual_review` tai ylimääräinen maksu vahvistuksen jälkeen
`payment.reorged`	Maksun sisältänyt lohko korvattiin — keskeytä toimitus
`payment.resolved`	Kauppiaan tai ylläpitäjän ratkaisu kirjattiin
`payment.canceled`	Peruit aikomuksen
`webhook.test`	Painoit Lähetä testitapahtuma (tai kutsuit `POST /v1/webhook-endpoints/{id}/test`)
`merchant.verification_updated`	Yrityksesi tunnistamisen tila muuttui
`payout.requested`	Nosto pyydettiin ja sen summa varattiin säilytyksessä olevasta saldostasi
`payout.approved`	Toinen jäsen hyväksyi noston; seuraavaksi GRYPHEMin ylläpitäjä tarkastaa sen
`payout.rejected`	GRYPHEMin ylläpitäjä hylkäsi noston; summa on taas käytettävissä
`payout.canceled`	Nosto peruttiin ennen lähettämistä; summa on taas käytettävissä
`payout.sent`	Alustan kuuma lompakko lähetti noston verkkoon (`data.tx_hash`)
`payout.completed`	Bitcart ilmoittaa noston transaktion vahvistuneen
`payout.failed`	Nostoa ei voitu lähettää; summa pysyy varattuna GRYPHEMin selvityksen ajan, ellei mitään ole voitu lähettää verkkoon

Maksu- ja nostotapahtumat alkavat, kun tilisi on aktivoitu live-maksuille. payout.*-tapahtumien store_id on null, koska saldot ja nostot kuuluvat koko organisaatiolle.

Sisältö

Runko on sama objekti, jonka saat kutsulla GET /v1/events/{event_id}:

{
  "event_id": "evt_01J…",
  "event_type": "payment.confirmed",
  "api_version": "2026-10-01",
  "created_at": "2026-10-20T12:00:00Z",
  "merchant_id": "org_…",
  "store_id": "store_01J…",
  "environment": "live",
  "object": { "type": "payment_intent", "id": "pi_01J…" },
  "data": {
    "status": "confirmed",
    "previous_status": "confirming",
    "status_reason": "bitcart_complete",
    "amount": "59.90",
    "currency": "EUR",
    "merchant_order_id": "order-123",
    "fulfillable": true,
    "quote": null,
    "totals": null
  }
}

data on tarkoituksella suppea. Live-maksuissa quote ja totals ovat null (ne kuvaavat pelkkään seurantaan perustuvaa käsittelyä); maksettu vara ja summa löytyvät aikomuksen processor-objektista kutsulla GET /v1/payment-intents/{id}. payment_intent.created sisältää kentät status, amount, currency, merchant_order_id ja checkout_url; webhook.test sisältää kentät message ja endpoint_id; merchant.verification_updated sisältää kentät kyb_status ja previous_kyb_status.

Otsakkeet

Otsake	Arvo
`Gryphem-Signature`	`t=<unix>,v1=<hex>` — useita `v1`-arvoja salaisuuden vaihdon aikana
`Gryphem-Event-Id`	Sama kuin `event_id`
`Gryphem-Event-Type`	Sama kuin `event_type`
`Gryphem-Delivery-Id`	Toimitus (`whd_…`) — yksi tapahtumaa ja päätepistettä kohden
`Gryphem-Delivery-Attempt`	1 ensimmäisellä yrityksellä, sitten 2, 3, …
`Content-Type`	`application/json`

Vastaanotin viidellä säännöllä

Todenna allekirjoitus raa’an rungon yli ennen sen jäsentämistä (näin). Vastaa virheessä 400.
Ohita kaksoiskappaleet event_id:n perusteella. Toimitukset tapahtuvat vähintään kerran; sama tapahtuma voi saapua useammin, myös manuaalisen uudelleenyrityksen jälkeen.
Kuittaa nopeasti millä tahansa 2xx-koodilla (muutamassa sekunnissa). Tee hidas työ jälkikäteen.
Älä luota järjestykseen. Käytä kenttää data.status ja lue aikomus tarvittaessa uudelleen.
Tarkista ennen peruuttamattomia toimia. Ennen tuotteiden lähettämistä tai arvon myöntämistä kutsu GET /v1/payment-intents/{id} ja tarkista fulfillable. Webhook on signaali; rajapinta on totuuden lähde.

Uudelleenyritykset, epäonnistuneet toimitukset ja uudelleenlähetys

Toimitus onnistuu millä tahansa 2xx-vastauksella. Kaikkea muuta — muu kuin 2xx, aikakatkaisu, yhteysvirhe — yritetään uudelleen eksponentiaalisella viiveellä ja satunnaistuksella.
Kun yritysten enimmäismäärä täyttyy, toimitus merkitään tilaan dead ja listataan ylläpitäjille; sitä ei koskaan pudoteta hiljaisesti.
Jokainen yritys kirjataan: alkuaika, kesto, vastauksen tila ja lyhyt, siistitty ote vastauksesta. Tarkastele niitä hallintapaneelissa tai kutsulla GET /v1/webhook-deliveries/{id}.
Yritä nyt: POST /v1/webhook-deliveries/{id}/retry asettaa toimituksen heti uudelleen jonoon. Sama event_id toimitetaan uudelleen, ja toimenpide kirjataan auditointilokiin.

POST/v1/webhook-deliveries/{webhook_delivery_id}/retrylive · tilin aktivoinnin jälkeen

Allekirjoitussalaisuuden vaihtaminen

POST /v1/webhook-endpoints/{id}/rotate-secret palauttaa uuden salaisuuden (näytetään kerran). Edellinen salaisuus allekirjoittaa rinnakkain ajan previous_secret_ttl_hours (oletus 24, enintään 168, tai 0, jolloin se vanhenee heti); tänä aikana jokaisessa toimituksessa on kaksi v1-allekirjoitusta. Ota uusi salaisuus käyttöön — tai määritä molemmat — ja anna vanhan vanhentua.

Mitä emme koskaan lähetä

Webhookit eivät koskaan sisällä API-avaimia, allekirjoitussalaisuuksia, asiakkaiden täydellisiä henkilötietoja tai lompakoiden laajennettuja julkisia avaimia. Kummankaan osapuolen lokeihin ei pidä koskaan kirjata Gryphem-Signature-arvoa yhdessä salaisuutesi kanssa.