Nastavení webhooku

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ů.

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.
• 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

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"]
  }'

Vyberte události

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

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

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.

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:

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.

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"}'

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í 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 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í. Emailit webhooky také automaticky vypíná po 3 dnech selhání; viz Opakování a selhání.

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. Odpověď obsahuje nový secret. Aktuální tajný klíč vrací také endpoint Načtení webhooku.

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í