Webhooky

Poštárna vie posielať dva druhy webhookov:

	Účtový webhook	Uzol `webhook` v automatizácii
Kedy volá	pri udalosti vo firme (nový kontakt, odhlásenie, doručenie ...)	keď kontakt dojde v automatizácii na uzol
Registrácia	`POST /api/v3/web-hooks` (kompatibilné so SmartEmailingom)	v grafe automatizácie
Tvar dát	pevný, ako SmartEmailing	vlastné telo so zástupnými značkami
Opakovanie	pri ďalšom behu (každých ~30 s), po 10 chybách v rade sa vypne	5 pokusov po 5 minútach

Účtové webhooky

Udalosti

`event`	Kedy	Telo
`new_contact`	nový kontakt	pole s jedným kontaktom
`updated_contact`	zmena kontaktu	pole s jedným kontaktom
`unsubscribed_contact`	odhlásenie (zo všetkého alebo zo zoznamu)	pole s jedným kontaktom a dôvodom
`sent_email`	e-mail odoslaný	objekt
`delivery_status`	doručené, mäkko alebo tvrdo vrátené (s odpoveďou servera)	objekt
`email_open`	otvorenie (len ľudia, strojové otvorenia sa nepočítajú)	objekt
`email_click`	klik (len ľudia)	objekt
`email_delivery_started`, `scoring_result_changed`, `engagement_level_changed`, `sms_delivery_status`	prijmú sa pre kompatibilitu, zatiaľ sa nikdy nevolajú

Registrácia

Prihlásenie ako pri API v3: HTTP Basic (e-mail člena firmy a API kľúč) alebo Bearer. Kľúč potrebuje modul settings na úrovni full (rola správcu účtu).

Požiadavka: POST /api/v3/web-hooks

curl -sS -X POST "https://www.postarna.cz/api/v3/web-hooks" \
  -u "$POSTARNA_USER:$POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "target_url": "https://crm.example.cz/postarna/webhook",
  "event": "new_contact",
  "basic_auth": {
    "login": "postarna",
    "password": "example-webhook-password"
  }
}
JSON

Odpoveď: 201 Created

{
  "status": "created",
  "meta": [],
  "id": 7
}

target_url: adresa http:// alebo https://, najviac 1 000 znakov. Volať sa dajú len verejné adresy (nie interné siete), presmerovania sa nesledujú.
basic_auth {login, password} (nepovinné): Poštárna ho pošle v hlavičke Authorization: Basic. Heslo sa ukladá šifrovane a nikdy sa nevracia (***).
Rovnaká adresa pre rovnakú udalosť druhýkrát = 409 Already exists; najviac 50 webhookov na firmu.
Nový webhook začína od najnovšieho záznamu: posiela len to, čo sa stane po registrácii.

Požiadavka: POST /api/v3/web-hooks

curl -sS -X POST "https://www.postarna.cz/api/v3/web-hooks" \
  -u "$POSTARNA_USER:$POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "target_url": "https://crm.example.cz/postarna/webhook",
  "event": "new_contact"
}
JSON

Odpoveď: 409 Conflict

{
  "status": "error",
  "meta": [],
  "message": "Already exists"
}

Požiadavka: GET /api/v3/web-hooks

curl -sS -X GET "https://www.postarna.cz/api/v3/web-hooks" \
  -u "$POSTARNA_USER:$POSTARNA_API_KEY"

Odpoveď: 200 OK

{
  "status": "ok",
  "meta": {
    "total_count": 2,
    "displayed_count": 2,
    "offset": 0,
    "limit": 500
  },
  "data": [
    {
      "id": 7,
      "url": "https://crm.example.cz/postarna/webhook",
      "method": "POST",
      "event": "new_contact",
      "active": 1,
      "timeout": 30,
      "last_response_code": null,
      "last_call_time": null,
      "errors_in_row": 0,
      "basic_auth": {
        "login": "***",
        "password": "***"
      }
    },
    {
      "id": 8,
      "url": "https://crm.example.cz/postarna/webhook",
      "method": "POST",
      "event": "unsubscribed_contact",
      "active": 1,
      "timeout": 30,
      "last_response_code": null,
      "last_call_time": null,
      "errors_in_row": 0,
      "basic_auth": {
        "login": "***",
        "password": "***"
      }
    }
  ]
}

Cez API v3 sa webhook upraviť nedá (rovnako ako v SmartEmailingu); zmažte ho a zaregistrujte znovu. V aplikácii v Nastaveniach › Dátové zdroje › Webhooky ho upravíte, vypnete, znova zapnete aj otestujete (API v1 PATCH a POST …/test na /tenants/{tenant}/account-webhooks):

Požiadavka: DELETE /api/v3/web-hooks/7

curl -sS -X DELETE "https://www.postarna.cz/api/v3/web-hooks/7" \
  -u "$POSTARNA_USER:$POSTARNA_API_KEY"

Odpoveď: 204 No Content

(bez tela)

Tvar dát

Každá položka je jeden POST s Content-Type: application/json a User-Agent: Postarna-Webhook/1. Kontaktové udalosti posielajú pole s jedným kontaktom v tvare API v3 SmartEmailingu (časy YYYY-MM-DD HH:MM:SS v miestnom čase firmy, príznaky 0 a 1, jazyk cs_CZ):

Webhook doručí (POST na vašu adresu): new_contact

[
  {
    "id": 1207,
    "guid": null,
    "emailaddress": "eva.horakova@example.cz",
    "domain": "example.cz",
    "name": "Eva",
    "surname": "Horáková",
    "titlesbefore": null,
    "titlesafter": null,
    "salution": null,
    "company": null,
    "street": null,
    "town": null,
    "postalcode": null,
    "country": null,
    "cellphone": null,
    "phone": null,
    "language": "cs_CZ",
    "birthday": null,
    "nameday": null,
    "gender": null,
    "notes": null,
    "realname": "Eva Horáková",
    "blacklisted": 0,
    "is_blacklisted": false,
    "hardbounced": 0,
    "softbounced": 0,
    "created": "2026-10-01 10:00:00",
    "updated": "2026-10-01 10:00:00",
    "created_at": "2026-10-01 10:00:00",
    "last_updated_at": "2026-10-01 10:00:00",
    "origin": "manual",
    "contactlists": [],
    "customfields": [],
    "event": "new_contact"
  }
]

Webhook doručí (POST na vašu adresu): unsubscribed_contact

[
  {
    "id": 1207,
    "guid": null,
    "emailaddress": "eva.horakova@example.cz",
    "domain": "example.cz",
    "name": "Eva",
    "surname": "Horáková",
    "titlesbefore": null,
    "titlesafter": null,
    "salution": null,
    "company": null,
    "street": null,
    "town": null,
    "postalcode": null,
    "country": null,
    "cellphone": null,
    "phone": null,
    "language": "cs_CZ",
    "birthday": null,
    "nameday": null,
    "gender": null,
    "notes": null,
    "realname": "Eva Horáková",
    "blacklisted": 0,
    "is_blacklisted": false,
    "hardbounced": 0,
    "softbounced": 0,
    "created": "2026-10-01 10:00:00",
    "updated": "2026-10-01 10:00:00",
    "created_at": "2026-10-01 10:00:00",
    "last_updated_at": "2026-10-01 10:00:00",
    "origin": "manual",
    "contactlists": [],
    "customfields": [],
    "event": "unsubscribed_contact",
    "reason": "admin",
    "unsubscribed_contactlist_ids": [],
    "campaign_type": null,
    "campaign_id": null,
    "email_statistic_id": null,
    "trigger_event": null
  }
]

E-mailové udalosti posielajú objekt:

sent_email, delivery_status, email_open, email_click

{
  "event": "email_click",
  "id": 81234,
  "contact": {"id": 1207, "emailaddress": "eva.horakova@example.cz"},
  "campaign_type": "newsletter",
  "campaign_id": 151,
  "email_statistic_id": "c151",
  "trigger_event": null,
  "sid": 50211,
  "url": "https://www.example.cz/novinky",
  "clicked_at": "2026-10-02 09:14:03"
}

sent_email a delivery_status majú miesto sid, url a clicked_at polia finished_at, delivery_status (delivered, softbounced, hardbounced) a remote_response (odpoveď poštového servera pri vrátení); email_open má sid a opened_at.
campaign_type: newsletter, automation, transactional, doi, test. email_statistic_id: c<id kampane>, alebo a<id automatizácie>:<kľúč uzla> (rovnaké ID ako v CSV štatistikách).
id e-mailovej udalosti je jedinečné; pri kontaktových udalostiach je id ID kontaktu.

Doručovanie a opakovanie

Poštárna kontroluje nové udalosti každých zhruba 30 sekúnd; jeden webhook dostane v jednom behu najviac 20 položiek, najstaršie prvé, každú samostatne.
Úspech = odpoveď 2xx do 30 sekúnd. Až potom sa posunie na ďalšiu položku.
Čokoľvek iné (iný stav, vypršanie času, odmietnutá adresa) sa počíta ako chyba a rovnaká položka prijde znovu pri ďalšom behu. Nič sa nepreskočí, ale tá istá položka môže prísť viackrát (doručenie aspoň raz).
Po 10 chybách v rade sa webhook sám vypne (active: 0); stav, posledný kód a počet chýb ukáže GET /api/v3/web-hooks. Znova ho zapnete v aplikácii (Nastavenia › Dátové zdroje › Webhooky, Zapnúť; chyby sa vynulujú) alebo zmazaním a novou registráciou.

Zabezpečenie

Poštárna webhooky nepodpisuje (žiadna hlavička s HMAC). Overujte ich takto:

vždy https://,
basic_auth s dlhým náhodným heslom a kontrolou hlavičky Authorization v konštantnom čase,
voliteľne tajná časť cesty (https://crm.example.sk/postarna/<nahodny-token>),
odpovedajte rýchlo (2xx) a spracovanie odložte do radu; spracovanie musí zvládnuť opakované doručenie.

Ukázkový príjemca: recept.

Uzol `webhook` v automatizácii

Uzol webhook

{"id": "crm", "type": "webhook", "config": {
  "url": "https://crm.example.cz/hooks/postarna?email={{df_emailaddress}}",
  "method": "POST",
  "headers": [{"name": "X-Source", "value": "postarna"}],
  "body": "{\"email\": \"{{df_emailaddress}}\", \"name\": \"{{df_name}}\", \"event\": \"cart\"}",
  "basicAuth": {"enabled": true, "username": "postarna", "password": "<heslo>"}}}

Zástupné značky kontaktu fungujú v adrese (hodnoty sa zakódujú do URL), v tele (pri JSON tele sa escapujú pre reťazec JSON) a v hodnotách hlavičiek. POST bez vlastnej hlavičky Content-Type posiela application/json; GET telo nemá.
Volá sa z radu; neúspech (iná odpoveď než 2xx, chyba siete) sa opakuje 5-krát po 5 minútach, potom sa zaznamená zlyhanie akcie other, na ktoré môže reagovať spúšťač action_failed.
Heslo basicAuth je len na zápis: detail ukazuje passwordSet: true; bez nového hesla zostane uložené. Kópia automatizácie heslo nekopíruje. Uloženie hesla potrebuje šifrovací kľúč servera (inak 503 unavailable / data_key).
Pozastavený scenár, zmazaný uzol alebo zmazaný kontakt zastaví ďalšie pokusy.
Volania (bez adries a osobných údajov) a ich výsledky ukazuje GET /automations/{id}/report v webhooks.

Webhooky

Účtové webhooky#

Udalosti#

Registrácia#

Tvar dát#

Doručovanie a opakovanie#

Zabezpečenie#

Uzol webhook v automatizácii#