# Konfigurácia (/sk/webhooks/configuration)





Každá organizácia má jednu cieľovú adresu webhookov a jeden aktívny signing secret (podpisový kľúč). Nakonfigurujte ich v Platform alebo zo svojho servera.

| Údaj            | Hodnota                                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| Základná URL    | `https://api.sandbox.tapaya.com` pre sandbox, `https://api.tapaya.com` pre produkčné prostredie            |
| Autentifikácia  | Server Secret Token v hlavičke `Authorization`. Pozrite si [Autentifikáciu](/platform-api#authentication). |
| Rozsah          | Jedna cieľová adresa na organizáciu                                                                        |
| Súvisiaci návod | [Overenie a testovanie](/webhooks/receiving)                                                               |

## Nastavte webhooky v Platform [#configure-in-the-platform]

Otvorte [API Keys](https://platform.tapaya.com/api-keys/) pre svoju organizáciu a nájdite **Webhooks**.

1. Zadajte svoju verejnú HTTPS URL.
2. Vyberte udalosti, ktoré potrebujete, alebo zapnite **Subscribe to all webhook types**.
3. Zapnite **Enable** a kliknite na **Save**.
4. Skopírujte signing secret a uložte ho na svojom serveri.
5. Odošlite [testovací webhook](/webhooks/receiving#send-a-test-webhook).

<Callout type="warn" title="Signing secret sa zobrazí iba raz">
  Skopírujte ho pri vytvorení alebo rotácii cieľovej adresy; neskôr ho už nemožno získať. Slúži iba na overenie prichádzajúcich webhookov. Konfiguračné požiadavky autorizuje váš Server Secret Token.
</Callout>

## Všetky operácie [#all-operations]

| Operácia                                             | Slúži na                                                                             |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [Uloženie cieľovej adresy](#save-a-destination)      | Vytvorenie alebo nahradenie aktuálneho odberu, prípadne rotácia jeho signing secret. |
| [Načítanie cieľovej adresy](#read-a-destination)     | Získanie aktuálnej URL, režimu odberu a stavu zapnutia.                              |
| [Odstránenie cieľovej adresy](#delete-a-destination) | Odstránenie odberu aj jeho frontu a histórie doručovania.                            |

## Správa cieľovej adresy [#manage-the-destination]

<Accordions type="multiple">
  <Accordion title="Uložte cieľovú adresu" id="save-a-destination">
    **Slúži na** pripojenie svojho HTTPS prijímača a výber udalostí na doručovanie.

    ```bash
    curl --request PUT \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME' \
      --header 'Content-Type: application/json' \
      --data '{
        "url": "https://payments.example.com/webhooks/tapaya",
        "eventTypes": ["payment.succeeded", "payment.failed", "payment.refund.succeeded"],
        "subscribeAllEventTypes": false,
        "enabled": true,
        "rotateSecret": false
      }'
    ```

    **Dobré vedieť:**

    * Táto operácia nahrádza uloženú konfiguráciu; nepridáva druhý endpoint.
    * Vytvorenie a explicitná rotácia vracajú `{"signingSecret":"twhsec_..."}`. Bežná aktualizácia vracia `{"signingSecret":null}`.
    * Uložte celý vrátený kľúč vrátane jeho prefixu. GET ho nikdy nevracia.
    * Organizáciu určuje váš token; neposielajte ID organizácie.

    **Parametre:**

    | Pole                     | Povinné | Význam                                                                                                                                 |
    | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
    | `url`                    | Áno     | Verejná HTTPS URL na porte 443, najviac 2 048 znakov, bez vložených prihlasovacích údajov alebo fragmentu.                             |
    | `eventTypes`             | Áno     | Pole názvov z [katalógu](/webhooks/events). Vyberte aspoň jeden, pokiaľ sa neprihlasujete na odber všetkých typov.                     |
    | `subscribeAllEventTypes` | Nie     | Predvolená hodnota je `false`. Nastavte `true` spolu s `eventTypes: []`, ak chcete zahrnúť všetky aktuálne aj budúce podporované typy. |
    | `enabled`                | Áno     | Pri hodnote `true` zachytáva nové zodpovedajúce udalosti a odosiela udalosti vo fronte.                                                |
    | `rotateSecret`           | Áno     | Pri hodnote `true` vygeneruje a vráti nový signing secret.                                                                             |
  </Accordion>

  <Accordion title="Načítajte cieľovú adresu" id="read-a-destination">
    **Slúži na** kontrolu uloženého odberu bez odhalenia jeho signing secret.

    ```bash
    curl 'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Dobré vedieť:**

    * GET vracia `404`, keď táto organizácia nemá cieľovú adresu.
    * Odbery všetkých typov vracajú prázdne pole `eventTypes` s `subscribeAllEventTypes: true`.
    * Odpoveď nikdy neobsahuje signing secret.
    * Pomocou `availableEventTypes` zostavíte výber udalostí bez napevno zapísaného katalógu.

    **Vracia:**

    | Pole                     | Význam                                                        |
    | ------------------------ | ------------------------------------------------------------- |
    | `url`                    | Uložená HTTPS cieľová adresa.                                 |
    | `eventTypes`             | Explicitné odbery alebo prázdne pole v režime všetkých typov. |
    | `subscribeAllEventTypes` | Či sú vybrané aktuálne aj budúce podporované typy.            |
    | `enabled`                | Či sú webhooky zapnuté.                                       |
    | `availableEventTypes`    | Všetky názvy udalostí, na ktorých odber sa môžete prihlásiť.  |
  </Accordion>

  <Accordion title="Odstráňte cieľovú adresu" id="delete-a-destination">
    **Slúži na** odpojenie organizácie a odstránenie jej doručení vo fronte aj histórie doručovania.

    ```bash
    curl --request DELETE \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Dobré vedieť:**

    * Úspech vracia HTTP `204` bez tela odpovede.
    * Požiadavka, ktorá sa už odosiela, môže prísť aj po odstránení.
    * Opätovné vytvorenie cieľovej adresy vygeneruje nový signing secret a neobnoví odstránené udalosti.
  </Accordion>
</Accordions>

## Pravidlá cieľovej adresy [#configuration]

### Zmena nastavení [#configuration-changes]

| Keď                              | Čo sa stane                                                                                                                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zmeníte URL, udalosti alebo kľúč | Nové udalosti použijú nové nastavenia. Udalosti vo fronte si ponechajú pôvodnú URL a kľúč, preto nechajte oboje funkčné, kým sa front nevyprázdni.                                 |
| Vypnete webhooky                 | Doručovanie z frontu sa pozastaví a nové udalosti sa nezachytávajú. Opätovné zapnutie obnoví spracovanie frontu, ale zmeškané zmeny sa spätne nedoplnia. Testy fungujú aj naďalej. |
| Odstránite cieľovú adresu        | Udalosti vo fronte a história doručovania sa odstránia. Požiadavka, ktorá sa už odosiela, môže ešte prísť. Opätovné vytvorenie vygeneruje nový signing secret.                     |

### Požiadavky na URL [#destination-requirements]

* Verejné HTTPS na porte 443. Localhost a súkromné siete sú odmietnuté a DNS sa pri každom pripojení kontroluje znova.
* Žiadne vložené prihlasovacie údaje, žiadny fragment a žiadne presmerovania.
* Žiadne vlastné autorizačné hlavičky. Namiesto toho overujte podpis Tapaya alebo pred URL, ktorá vyžaduje vlastný kľúč, umiestnite serverový adaptér.

## Chyby [#errors]

Požiadavky na konfiguráciu zlyhávajú s týmito odpoveďami. Prijímač, ktorý doručenie odmietne alebo ho nezachytí, je iný problém; pozrite si časť [Riešenie chýb](/webhooks/receiving#handle-errors).

| Odpoveď       | Význam                                                                                                    |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `400` pri PUT | Neplatná URL, nepodporovaný typ udalosti, chýbajúce povinné pole alebo prázdny explicitný výber udalostí. |
| `401`         | Server Secret Token chýba alebo je neplatný.                                                              |
| `404` pri GET | Pre autentifikovanú organizáciu neexistuje cieľová adresa.                                                |

Pokračujte na [overenie podpisu a testovacie doručenie](/webhooks/receiving).