# Webhooky (/sk/webhooks)



Webhooky oznamujú vášmu serveru zmeny vo vašej organizácii Tapaya. Používajte rovnakú integráciu pre platby v predajni aj online platby bez ohľadu na spracovateľa platieb.

## Ako to funguje [#how-it-works]

<WebhookLifecycle senderLabel="Tapaya" receiverLabel="Váš server" label="Potvrdená zmena zaradí udalosť do frontu. Tapaya ju podpíše a odošle. Váš prijímač ju overí a uloží. Odpoveď 2xx potvrdí doručenie; pri chybe sa opakuje krok odoslania, najviac 12 pokusov, potom sa doručovanie zastaví." event="Uložená zmena" queue="Udalosť vo fronte" send="Podpísaný POST" receive="Overiť a uložiť" delivered="Doručené" />

Nakonfigurujte jednu HTTPS cieľovú adresu pre každú organizáciu a vyberte požadované udalosti. Tapaya odošle HTTP `POST` so snímkou vo formáte JSON a podpisom. Overte podpis, uložte udalosť a vráťte úspešnú odpoveď ešte pred spracovaním vlastnej obchodnej logiky.

Môžete sa prihlásiť na odber jednotlivých typov alebo všetkých podporovaných typov. Odber všetkých typov bude v budúcnosti prijímať aj novo podporované typy, preto ignorujte typy, ktoré vaša aplikácia nepozná.

## Rýchla integrácia [#quick-integration]

<div className="fd-steps [&_h3]:fd-step">
  ### Uložte cieľovú adresu [#save-a-destination]

  V Platform otvorte **API Keys** a potom **Webhooks**. Zadajte svoju HTTPS URL, vyberte požadované udalosti a uložte. Signing secret (podpisový kľúč) si skopírujte hneď; zobrazí sa iba raz. Pozrite si [Konfigurácia](/webhooks/configuration).

  ### Overte každú požiadavku [#verify-each-request]

  Vypočítajte HMAC-SHA256 z časovej pečiatky, bodky a pôvodného tela pomocou svojho signing secret a porovnajte ho s `X-Tapaya-Signature`. Pozrite si [Skontrolujte podpis](/webhooks/receiving#check-the-signature).

  ### Uložte udalosť a potom vráťte 2xx [#store-the-event-then-return-2xx]

  Uložte udalosť s jedinečným `id`, do 10 sekúnd odpovedzte `2xx` a spracujte ju až potom. Pozrite si [Uložte a potvrďte](/webhooks/receiving#store-and-acknowledge).

  ### Odošlite testovací webhook [#send-a-test-webhook]

  Na tej istej stránke použite testovaciu akciu na odoslanie podpísaného `webhook.test`. Pozrite si [Odošlite testovací webhook](/webhooks/receiving#send-a-test-webhook).
</div>

## Obálka udalosti [#event-envelope]

Každá udalosť používa túto spoločnú štruktúru. Snímka zdroja v poli `data` závisí od typu udalosti.

```json
{
  "id": "019a0000-0000-7000-8000-000000000001",
  "type": "payment.succeeded",
  "apiVersion": "1",
  "organizationId": "019a0000-0000-7000-8000-000000000002",
  "merchantId": "019a0000-0000-7000-8000-000000000005",
  "createdAt": "2026-10-30T12:00:00.000000Z",
  "data": {
    "payment": {
      "id": "019a0000-0000-7000-8000-000000000003",
      "token": "example_payment_token",
      "merchantId": "019a0000-0000-7000-8000-000000000005",
      "status": "success",
      "statusId": 2,
      "requestedAmount": 10000,
      "requestedCurrencyId": 203,
      "settlementAmount": 10000,
      "settlementCurrencyId": 203
    }
  }
}
```

| Pole             | Význam                                                                                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`             | Jedinečné ID udalosti. Použite ho na deduplikáciu doručení. Opakované pokusy zachovávajú rovnaké ID.                          |
| `type`           | Názov udalosti z [katalógu udalostí](/webhooks/events).                                                                       |
| `apiVersion`     | Identifikátor schémy payloadu, momentálne reťazec `"1"`.                                                                      |
| `organizationId` | Organizácia, ktorej udalosť patrí. Skontrolujte, či zodpovedá vašej integrácii.                                               |
| `merchantId`     | Obchodník, ktorému zdroj patrí. Pri starších platbách s neurčeným vlastníctvom alebo pri diagnostickom teste môže byť `null`. |
| `createdAt`      | Čas UTC zachytenia udalosti, nie čas jej doručenia.                                                                           |
| `data`           | Nemenná snímka zdroja v čase zachytenia.                                                                                      |

Sumy sú celé čísla v najmenších jednotkách meny daného poľa. Napríklad `10000` s číselným ID meny ISO 4217 `203` znamená 100,00 CZK. Požadované a zúčtovacie sumy môžu byť v rôznych menách.

Každý typ udalosti vkladá do `data` vlastnú snímku. Všetky štruktúry payloadu a hodnoty stavov nájdete v časti [Typy udalostí](/webhooks/events).

## Pravidlá doručovania [#delivery-rules]

Tapaya odošle udalosť hneď po uložení jej zmeny a posiela ju dovtedy, kým váš server neodpovie `2xx`.

| Pravidlo         | Správanie                                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| Potvrdenie       | Akákoľvek odpoveď `2xx` do 10 sekúnd. Presmerovania sa nesledujú.                                        |
| Opakované pokusy | Najviac 12 pokusov počas približne 20 hodín s čakaním 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 a 360 minút. |
| Poradie          | Nie je zaručené. Doručenie prebehne aspoň raz, preto počítajte s duplicitami a staršími snímkami.        |
| Súbeh            | 2 požiadavky naraz na organizáciu, spoločne s ručnými testami. Ostatné udalosti čakajú vo fronte.        |

Neúspešné doručenie nikdy nezmení samotnú platbu a minulé doručenia nie je možné odoslať znova. Ak potrebujete po výpadku dobehnúť zmeny, načítajte aktuálny stav cez [API pre platby a obchodníkov](/platform-api/reporting).

## Začnite s integráciou [#start-integrating]

<Cards>
  <Card title="Nakonfigurujte cieľovú adresu" href="/webhooks/configuration">
    Nastavte URL, vyberte udalosti a uložte signing secret (podpisový kľúč).
  </Card>

  <Card title="Prejdite si typy udalostí" href="/webhooks/events">
    Nájdite presnú podmienku odoslania každej udalosti platby, obchodníka a onboardingu.
  </Card>

  <Card title="Overte a otestujte" href="/webhooks/receiving">
    Overte podpisy a odošlite diagnostický webhook.
  </Card>
</Cards>