# Webhooky (/cs/webhooks)



Webhooky oznamují vašemu serveru změny v organizaci Tapaya. Stejnou integraci použijete pro platby v prodejně i online bez ohledu na zpracovatele plateb.

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

<WebhookLifecycle senderLabel="Tapaya" receiverLabel="Váš server" label="Uložená změna zařadí událost do fronty. Tapaya ji podepíše a odešle. Příjemce ji ověří a uloží. Odpověď 2xx potvrdí doručení; při chybě se odeslání opakuje, nejvýše 12 pokusů, pak se zastaví." event="Uložená změna" queue="Událost ve frontě" send="Podepsaný POST" receive="Ověření a uložení" delivered="Doručeno" />

Pro každou organizaci nastavte jednu cílovou HTTPS adresu a vyberte požadované události. Tapaya odešle HTTP `POST` se snímkem dat v JSON a podpisem. Ověřte podpis, uložte událost a vraťte úspěšnou odpověď ještě před spuštěním vlastní aplikační logiky.

Můžete odebírat jednotlivé typy nebo všechny podporované typy. Odběr všech typů zahrnuje i typy přidané v budoucnu, proto ignorujte typy, které vaše aplikace nezná.

## Rychlá integrace [#quick-integration]

<div className="fd-steps [&_h3]:fd-step">
  ### Uložte cílovou adresu [#save-a-destination]

  V Platform otevřete **API Keys** a poté **Webhooks**. Zadejte HTTPS URL, vyberte požadované události a uložte. Hned zkopírujte podpisový klíč; zobrazí se jen jednou. Viz [Nastavení](/webhooks/configuration).

  ### Ověřte každý požadavek [#verify-each-request]

  Vypočítejte HMAC-SHA256 z časového razítka, tečky a původního těla pomocí podpisového klíče a porovnejte ho s `X-Tapaya-Signature`. Viz [Ověřte podpis](/webhooks/receiving#check-the-signature).

  ### Uložte událost a vraťte 2xx [#store-the-event-then-return-2xx]

  Uložte událost s jedinečným `id`, odpovězte `2xx` do 10 sekund a zpracujte ji až poté. Viz [Uložte a potvrďte](/webhooks/receiving#store-and-acknowledge).

  ### Odešlete testovací webhook [#send-a-test-webhook]

  Na stejné stránce odešlete testovací akcí podepsaný `webhook.test`. Viz [Odešlete testovací webhook](/webhooks/receiving#send-a-test-webhook).
</div>

## Obálka události [#event-envelope]

Každá událost používá tuto společnou strukturu. Snímek objektu uvnitř `data` závisí na typu události.

```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 události. Použijte ho k odstranění duplicitních doručení. Při opakování zůstává stejné.                 |
| `type`           | Název události z [katalogu událostí](/webhooks/events).                                                              |
| `apiVersion`     | Identifikátor schématu payloadu, aktuálně řetězec `"1"`.                                                             |
| `organizationId` | Organizace, které událost patří. Ověřte, že odpovídá vaší integraci.                                                 |
| `merchantId`     | Obchodník, kterému objekt patří. U starších plateb s neurčeným vlastníkem nebo diagnostického testu může být `null`. |
| `createdAt`      | Čas zachycení události v UTC, nikoli čas doručení.                                                                   |
| `data`           | Neměnný snímek objektu v okamžiku zachycení.                                                                         |

Částky jsou celá čísla v nejmenších jednotkách měny daného pole. Například `10000` s číselným ID měny ISO 4217 `203` znamená 100,00 CZK. Požadovaná a zúčtovaná částka mohou používat různé měny.

Každý typ události vkládá do `data` vlastní snímek. Všechny tvary payloadu a hodnoty stavu najdete na stránce [Typy událostí](/webhooks/events).

## Pravidla doručování [#delivery-rules]

Tapaya odešle událost, jakmile se její změna uloží, a odesílá ji znovu, dokud váš server neodpoví `2xx`.

| Pravidlo  | Chování                                                                                                    |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| Potvrzení | Jakákoli odpověď `2xx` do 10 sekund. Přesměrování se nenásledují.                                          |
| Opakování | Nejvýše 12 pokusů během přibližně 20 hodin s prodlevami 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 a 360 minut. |
| Pořadí    | Není zaručené. Doručení probíhá alespoň jednou, počítejte proto s duplicitami a staršími snímky.           |
| Souběh    | 2 požadavky současně na organizaci, sdílené s ručními testy. Ostatní události čekají ve frontě.            |

Neúspěšné doručení nikdy nemění samotnou platbu a minulá doručení nelze odeslat znovu. Pro dohnání stavu po výpadku načtěte aktuální stav přes [API plateb a obchodníků](/platform-api/reporting).

## Začněte s integrací [#start-integrating]

<Cards>
  <Card title="Nastavte cílovou adresu" href="/webhooks/configuration">
    Nastavte URL, vyberte události a uložte podpisový klíč.
  </Card>

  <Card title="Projděte typy událostí" href="/webhooks/events">
    Zjistěte přesné spouštěče událostí plateb, obchodníků a onboardingu.
  </Card>

  <Card title="Ověřte a otestujte" href="/webhooks/receiving">
    Ověřujte podpisy a odešlete diagnostický webhook.
  </Card>
</Cards>