# Nastavení webhooku

> Vytvořte endpoint webhooku, vyberte jeho události, přidejte filtry obsahu, odešlete testovací událost, webhook zapněte nebo vypněte a vyměňte jeho tajný klíč.

Tento návod ukazuje, jak vytvořit webhook, omezit ho na události, které potřebujete, a ověřit, že váš endpoint dostává podepsané požadavky. Vše můžete udělat ve webovém rozhraní nebo přes [API webhooků](/cs/docs/api-reference/webhooks/).

## Než začnete

- Veřejná URL, která přijímá požadavky `POST`. Důrazně doporučujeme HTTPS. URL na `localhost` nebo v privátních rozsazích IP adres Emailit odmítne; pro lokální vývoj použijte tunel, například ngrok nebo Cloudflare Tunnel.
- Endpoint, který si ponechá surové tělo požadavku, aby mohl [ověřit podpis](/cs/docs/webhooks/request-signature/).
- Pro práci přes API klíč s oprávněním **Full Access**.
- Volné místo pro webhook. Tarif Pay as you go zahrnuje 3 endpointy, tarif Pro 10 a tarify Business a Custom 100.

## Vytvořte webhook

**Webové rozhraní**

  1. **Otevřete webhooky.** Přejděte do **Email API → Webhooks** a vyberte **Add webhook**.

  2. **Zadejte název a URL.** Název musí být ve workspace jedinečný, například `Production events`. URL je váš endpoint, například `https://acme.com/webhooks/emailit`. Vyberte **Create**.

  3. **Zkopírujte tajný klíč.** Dialogové okno zobrazí tajný klíč webhooku začínající na `whsec_` spolu s upozorněním „You can see the webhook secret only once. Store it safely.“ Zkopírujte ho do prostředí své aplikace, například jako `EMAILIT_WEBHOOK_SECRET`, a vyberte **Done**.

  Webhook vytvořený ve webovém rozhraní odebírá všechny typy událostí. Otevře se karta **Settings** webhooku, kde ho můžete omezit.

**API**

  Zavolejte endpoint [Vytvoření webhooku](/cs/docs/api-reference/webhooks/create/). Typy událostí uveďte v poli `events`, nebo nastavte `all_events` na `true`. Odpověď `201` obsahuje `secret`.

```bash
curl https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://acme.com/webhooks/emailit",
    "events": ["email.delivered", "email.bounced", "email.complained"]
  }'
```

  Na rozdíl od webového rozhraní má API ve výchozím stavu `all_events: false` a prázdný seznam `events`, takže webhook vytvořený bez jednoho z nich nedostane nic. Duplicitní název vrací `409`; při dosažení limitu endpointů vašeho tarifu API vrací `422` s `usage.used` a `usage.limit`.

## Vyberte události

Webhook dostává buď všechny typy událostí, nebo jen typy, které vyberete.

**Webové rozhraní**

  Na kartě **Settings** webhooku vypněte **All events** a pak vyberte typy v panelu **Events**. Události jsou seskupené podle zdroje (**Emails**, **Domains**, **Audiences**, **Subscribers**, **Contacts**, **Templates**, **Suppressions**, **Email Verifications**, **Email Verification Lists**) a každá skupina má zaškrtávací políčko **Select all**. Vyberte **Save**.

  Výběr neuvádí všechny typy, které Emailit odesílá. Události `email.canceled`, `email.held`, `email.unsubscribed`, `email.resubscribed`, `subscriber.resubscribed` a `campaign.*` dostávají webhooky se zapnutým **All events**, nebo je můžete do seznamu přidat přes API. Skupina **Deprecated** obsahuje staré názvy událostí, které se už neodesílají. Viz [Typy událostí](/cs/docs/webhooks/event-types/).

**API**

  Zavolejte endpoint [Úprava webhooku](/cs/docs/api-reference/webhooks/update/). Pole `events` nahradí celý seznam. Nastavení `all_events` na `true` seznam vyprázdní.

```bash
curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all_events": false, "events": ["email.received", "email.held", "email.canceled"]}'
```

## Filtrujte události podle obsahu

Pro, Business, Custom

Filtr obsahu doručí událost, jen pokud její data odpovídají vašim pravidlům. Filtry se uplatňují navíc k výběru událostí: událost musí být odebíraná *a* zároveň odpovídat filtru.

Použijte ho k rozdělení provozu mezi endpointy, například jeden webhook na každou produktovou řadu, nebo k zahození událostí, které byste jinak v kódu ignorovali.

- **Režim shody:** **All rules match** (`all`), nebo **Any rule matches** (`any`).
- **Pravidla:** nejvýše 25. Každé pravidlo má pole, operátor a hodnotu.
- **Pole:** cesta s tečkami do `data.object` události, například `to`, `status`, `meta.plan` nebo u událostí prokliku `link.url`. Předpona `payload.` je volitelná, takže `payload.from` a `from` znamenají totéž.
- **Porovnání rozlišují velikost písmen** a porovnávají hodnoty jako text, kromě `greater_than` a `less_than`, které porovnávají čísla.

| Operátor | Shoda nastane, když pole |
| --- | --- |
| `equals` / `not_equals` | Je / není přesně rovno hodnotě. |
| `contains` / `not_contains` | Obsahuje / neobsahuje hodnotu. |
| `starts_with` / `ends_with` | Začíná / končí hodnotou. |
| `greater_than` / `less_than` | Je číslo větší / menší než hodnota. |
| `is_set` / `is_not_set` | Má neprázdnou hodnotu / chybí nebo je prázdné. Hodnota není potřeba. |
| `in` / `not_in` | Je / není rovno jedné z hodnot v poli. Pole hodnot pošlete přes API jako v příkladu níže. |

**Webové rozhraní**

  Na kartě **Settings** webhooku najděte panel **Filter**. Zvolte režim shody, přidejte pravidla s polem, operátorem a hodnotou a vyberte **Save**. Když pravidla necháte prázdná, doručí se všechny odebírané události. V tarifu Pay as you go je panel zamčený a zobrazuje **Upgrade**.

**API**

  Pošlete `filter` s endpointem [Vytvoření webhooku](/cs/docs/api-reference/webhooks/create/) nebo [Úprava webhooku](/cs/docs/api-reference/webhooks/update/). Hodnotou `null` filtr odeberete. V tarifu Pay as you go vrací filtr `403` s `"error": "plan_required"`.

```bash
curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": "all",
      "rules": [
        { "field": "to", "operator": "ends_with", "value": "@acme.com" },
        { "field": "meta.plan", "operator": "in", "value": ["pro", "business"] }
      ]
    }
  }'
```

Další příklady:

| Cíl | Pravidlo |
| --- | --- |
| Jen pošta přijatá na jednu adresu | `to` `equals` `support@inbound.acme.com` |
| Jen jedna doména odesílatele | `from` `ends_with` `@billing.acme.com` |
| Jen e-maily, které jste označili metadaty | `meta.source` `equals` `checkout` |
| Jen prokliky na vaši stránku s ceníkem | `link.url` `starts_with` `https://acme.com/pricing` |
| Jen e-maily s ID zákazníka | `meta.customer_id` `is_set` |

> **Pole se mezi typy událostí liší:** Pravidlo na pole, které událost nemá, nikdy neodpovídá. Události stavu e-mailu mají `to` a `from` na nejvyšší úrovni, ale události prokliku a načtení je mají vnořené jako `email.rcpt_to` a `email.mail_from` a události kontaktů mají `email`. S režimem **All rules match** webhook filtrovaný podle `to` potichu zahodí každý proklik. Používejte samostatné webhooky pro každý druh událostí, nebo **Any rule matches** s jedním pravidlem pro každý tvar obsahu. Názvy polí ověřte v [referenci událostí](/cs/docs/webhooks/event-types/).

Pokud workspace přejde na tarif Pay as you go, stávající filtry zůstanou uložené, ale ignorují se a doručí se všechny odebírané události.

## Odešlete testovací událost

Test okamžitě pošle na vaši URL jednu ukázkovou událost podepsanou aktuálním tajným klíčem webhooku. Odebírané události a filtry se ignorují, požadavek se neopakuje a nezobrazí se na kartě **Requests**. Každý webhook umožňuje 5 testů za minutu.

**Webové rozhraní**

  Na stránce webhooku otevřete nabídku akcí (**…**) a vyberte **Send test**. Zvolte typ události a vyberte **Send test**. Dialogové okno zobrazí „Your endpoint returned 200“ (nebo stav, který váš endpoint vrátil) a tělo odpovědi. „Could not reach the endpoint“ znamená, že požadavek nedostal HTTP odpověď, například kvůli chybě DNS, vypršení časového limitu nebo přesměrování.

**API**

  Zavolejte endpoint [Odeslání testovací události](/cs/docs/api-reference/webhooks/test/) s libovolným typem události.

```bash
curl https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/test \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "email.delivered"}'
```

  Odpověď obsahuje `ok`, `status_code`, `body` (odpověď vašeho endpointu, nejvýše 2 000 znaků), `type` a odeslaný `payload`.

Testovací události používají ukázková data s `event_id` začínajícím na `evt_test_` a jejich tvar se může od skutečných událostí mírně lišit. Handler stavte podle [reference událostí](/cs/docs/webhooks/event-types/) a ověřte ho skutečným odesláním.

## Zapněte nebo vypněte webhook

Vypnutím webhooku zastavíte doručování, aniž byste přišli o jeho nastavení, například během údržby.

- **Webové rozhraní:** otevřete nabídku akcí a vyberte **Disable webhook**, nebo **Enable webhook**. Na stránce webhooku se zobrazí stav **Enabled**, nebo **Disabled**.
- **API:** zavolejte endpoint [Úprava webhooku](/cs/docs/api-reference/webhooks/update/) s `{"enabled": false}`, nebo `{"enabled": true}`.

Dokud je webhook vypnutý, nové události se pro něj do fronty nezařazují a požadavky, které už čekají na opakování, jsou pozastavené. Události, které nastanou během vypnutí, se později nedoručí; pokud je potřebujete, načtěte je přes [API událostí](/cs/docs/logs/events/#reconcile-missed-webhook-events). Emailit webhooky také automaticky vypíná po 3 dnech selhání; viz [Opakování a selhání](/cs/docs/webhooks/retries-and-failures/).

Smazáním webhooku se zahodí všechny jeho čekající události.

## Vyměňte tajný klíč

Tajný klíč vyměňte, pokud mohl uniknout, nebo v rámci běžné bezpečnostní údržby.

- **Webové rozhraní:** otevřete nabídku akcí, vyberte **Webhook secret** a pak **Reset**. Nový tajný klíč se zobrazí jen jednou.
- **API:** zavolejte endpoint [Výměna tajného klíče](/cs/docs/api-reference/webhooks/reset-secret/). Odpověď obsahuje nový `secret`. Aktuální tajný klíč vrací také endpoint [Načtení webhooku](/cs/docs/api-reference/webhooks/get/).

Starý tajný klíč okamžitě přestane fungovat a každý další požadavek, včetně opakování starších událostí, se podepisuje novým. Pokud chcete klíč vyměnit bez odmítání požadavků, nechte endpoint na několik minut přijímat oba klíče, obnovte tajný klíč, nasaďte novou hodnotu a pak starou odeberte.

## Ověřte, že vše funguje

1. Odešlete testovací událost a ověřte, že váš endpoint vrací `2xx`.
2. Odešlete skutečný e-mail, nebo vyvolejte událost, kterou odebíráte.
3. Na kartě **Requests** webhooku má požadavek stav **Delivered**. Čas **Last used** webhooku se aktualizuje.

## Související

  - [Ověření podpisů](/cs/docs/webhooks/request-signature/)
  - [Požadavky webhooků](/cs/docs/webhooks/webhook-requests/)
  - [Typy událostí](/cs/docs/webhooks/event-types/)
  - [Opakování a selhání](/cs/docs/webhooks/retries-and-failures/)

---
Zdroj: https://emailit.com/cs/docs/webhooks/set-up/