# Nastavení (/cs/webhooks/configuration)





Každá organizace má jednu cílovou adresu webhooku a jeden aktivní signing secret (podpisový klíč). Nastavte je v Platform nebo ze serveru.

| Údaj                 | Hodnota                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| Základní URL         | `https://api.sandbox.tapaya.com` pro sandbox, `https://api.tapaya.com` pro produkci              |
| Autentizace          | Server Secret Token v hlavičce `Authorization`. Viz [Autentizace](/platform-api#authentication). |
| Rozsah               | Jedna cílová adresa na organizaci                                                                |
| Související průvodce | [Ověření a testování](/webhooks/receiving)                                                       |

## Nastavení v Platform [#configure-in-the-platform]

Otevřete [API Keys](https://platform.tapaya.com/api-keys/) pro svou organizaci a najděte **Webhooks**.

1. Zadejte veřejnou HTTPS adresu.
2. Vyberte potřebné události nebo zapněte **Subscribe to all webhook types**.
3. Zapněte **Enable** a klikněte na **Save**.
4. Zkopírujte podpisový klíč a uložte ho na server.
5. Odešlete [testovací webhook](/webhooks/receiving#send-a-test-webhook).

<Callout type="warn" title="Podpisový klíč se zobrazí jen jednou">
  Zkopírujte ho při vytvoření nebo obměně cílové adresy; později ho již nelze načíst. Slouží pouze k ověření příchozích webhooků. Požadavky na nastavení autorizuje váš Server Secret Token.
</Callout>

## Všechny operace [#all-operations]

| Operace                                        | K čemu slouží                                                    |
| ---------------------------------------------- | ---------------------------------------------------------------- |
| [Uložení cílové adresy](#save-a-destination)   | Vytvořit nebo nahradit aktuální odběr či obměnit podpisový klíč. |
| [Načtení cílové adresy](#read-a-destination)   | Získat aktuální URL, režim odběru a stav povolení.               |
| [Smazání cílové adresy](#delete-a-destination) | Odstranit odběr, frontu doručování i historii.                   |

## Správa cílové adresy [#manage-the-destination]

<Accordions type="multiple">
  <Accordion title="Uložení cílové adresy" id="save-a-destination">
    **Slouží k** připojení HTTPS příjemce a výběru doručovaných událostí.

    ```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é vědět:**

    * Operace nahrazuje uložené nastavení; nepřidává druhý endpoint.
    * Vytvoření a výslovná obměna vracejí `{"signingSecret":"twhsec_..."}`. Běžná aktualizace vrací `{"signingSecret":null}`.
    * Uložte celý vrácený klíč včetně prefixu. GET ho nikdy nevrací.
    * Organizaci určuje váš token; ID organizace neposílejte.

    **Parametry:**

    | Pole                     | Povinné | Význam                                                                                                          |
    | ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------- |
    | `url`                    | Ano     | Veřejná HTTPS adresa na portu 443, nejvýše 2 048 znaků, bez vložených přihlašovacích údajů či fragmentu.        |
    | `eventTypes`             | Ano     | Pole názvů z [katalogu](/webhooks/events). Vyberte alespoň jeden typ, pokud neodebíráte všechny.                |
    | `subscribeAllEventTypes` | Ne      | Výchozí hodnota je `false`. Nastavte `true` s `eventTypes: []` pro všechny současné i budoucí podporované typy. |
    | `enabled`                | Ano     | Při hodnotě `true` zachycuje nové odpovídající události a doručuje události z fronty.                           |
    | `rotateSecret`           | Ano     | Při hodnotě `true` vytvoří a vrátí nový podpisový klíč.                                                         |
  </Accordion>

  <Accordion title="Načtení cílové adresy" id="read-a-destination">
    **Slouží k** zobrazení uloženého odběru bez odhalení podpisového klíče.

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

    **Dobré vědět:**

    * Pokud organizace nemá cílovou adresu, GET vrací `404`.
    * Odběr všech typů vrací prázdné pole `eventTypes` a `subscribeAllEventTypes: true`.
    * Odpověď nikdy neobsahuje podpisový klíč.
    * Pomocí `availableEventTypes` sestavíte výběr událostí, aniž byste katalog uváděli natvrdo v kódu.

    **Vrací:**

    | Pole                     | Význam                                                         |
    | ------------------------ | -------------------------------------------------------------- |
    | `url`                    | Uložená cílová HTTPS adresa.                                   |
    | `eventTypes`             | Výslovně vybrané odběry nebo prázdné pole v režimu všech typů. |
    | `subscribeAllEventTypes` | Zda jsou vybrány současné i budoucí podporované typy.          |
    | `enabled`                | Zda jsou webhooky zapnuté.                                     |
    | `availableEventTypes`    | Všechny názvy událostí, které můžete odebírat.                 |
  </Accordion>

  <Accordion title="Smazání cílové adresy" id="delete-a-destination">
    **Slouží k** odpojení organizace a odstranění jejích čekajících doručení a historie doručování.

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

    **Dobré vědět:**

    * Úspěch vrací HTTP `204` bez těla odpovědi.
    * Již odesílaný požadavek může dorazit i po smazání.
    * Opětovné vytvoření cílové adresy vytvoří nový podpisový klíč a neobnoví smazané události.
  </Accordion>
</Accordions>

## Pravidla cílové adresy [#configuration]

### Změna nastavení [#configuration-changes]

| Když                            | Co se stane                                                                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Změníte URL, události nebo klíč | Nové události použijí nové nastavení. Události ve frontě si ponechají starou URL i klíč, proto udržujte obojí funkční, dokud se fronta nevyprázdní.             |
| Vypnete webhooky                | Doručování z fronty se pozastaví a nové události se nezachycují. Opětovné zapnutí obnoví frontu, ale zmeškané změny se zpětně nedoplní. Testy fungují i nadále. |
| Smažete cílovou adresu          | Události ve frontě i historie doručování se odstraní. Již odesílaný požadavek může stále dorazit. Opětovné vytvoření vytvoří nový podpisový klíč.               |

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

* Veřejné HTTPS na portu 443. Localhost a privátní sítě se odmítají a DNS se znovu ověřuje při každém připojení.
* Žádné vložené přihlašovací údaje, žádný fragment a žádná přesměrování.
* Žádné vlastní autorizační hlavičky. Místo toho ověřujte podpis Tapaya, nebo před URL, která vyžaduje vlastní klíč, umístěte serverový adaptér.

## Chyby [#errors]

Požadavky na nastavení selhávají s těmito odpověďmi. Příjemce, který doručení odmítne nebo ho nepřijme, je jiný problém; viz [Řešení chyb](/webhooks/receiving#handle-errors).

| Odpověď       | Význam                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `400` při PUT | Neplatná URL, nepodporovaný typ události, chybějící povinné pole nebo prázdný výslovný výběr událostí. |
| `401`         | Server Secret Token chybí nebo je neplatný.                                                            |
| `404` při GET | Pro autentizovanou organizaci neexistuje cílová adresa.                                                |

Pokračujte na [ověření podpisu a test doručení](/webhooks/receiving).