Webhooky

Webhooky jsou způsob jak získávat upozornění z Retina o různých událostech. Místo periodického stahování informací přes API si můžete vytvořit webhook a my vám na určenou adresu budeme posílat upozornění o změnách v Retinu v reálném čase.

Webhooky jsou prémiová funkcionalita, která je součástí rozšíření „API & Webhooky“. Pokud máte aktivní rozšíření „API & Webhooky“, tak poté naleznete nastavení webhooků v Nastavení > Webhooky, odsud si můžete vytvořit webhook a monitorovat již existující.

Tvorba webhooku

Přidejte si na vašem serveru novou url adresu, kterou použijete pro přijímání webhooků, např. vas-eshop.cz/webhook-retino, což bude adresa, na kterou vám budeme posílat metodou POST ve formátu JSON upozornění na vybrané události.

Poté přejděte do Nastavení > Webhooky a vytvořte nový webhook a vložte tam tuto nově vytvořenou url adresu z vašeho eshopu a vyberte události, na které chcete být informováni. Webhooky se nastavují na úrovni celého účtu a takže nejsou omezeny na jednotlivé uživatele.

Jakmile budete mít nový webhook vytvořený, můžete zkusit odeslat testovací událost, kterou najdete v detailu tohoto nově vytvořeného webhooku. Po odeslání testovací události se vám zobrazí data odeslaná na váš server, stavový kód odpovědi vašeho serveru a data odeslaná vaším serverem jako odpověď. Tyto údaje jsou velmi užitečné při hledání chyb v integraci.

Zabezpečení

Všechny události odeslané naším serverem na URL adresu vašeho webhooku obsahují hlavičku X-Retino-Secret ve tvaru:

X-Retino-Secret: <token>

Ta slouží k authentizaci požadavku. Tuto hlavičku naleznete v nastavení jednolivých webhooků.

Obnovení tajného tokenu

Pokud máte podezření, že váš token byl kompromitován, můžete v nastavení webhooku takový token obnovit. POZOR, po obnovaní tokenu nebude váš server schopný pravděpodobně po dobu, než nasadíte nový token, přijímat webhooky.

Používejte HTTPS

Důrazně doporučujeme, aby komunikace probíhala přes šifrovaný protokol HTTPS. Pokud váš webhook bude pod protokolem HTTP, budeme vás na to upozorňovat v nastavení webhooků.

Typy událostí

Webhook může být navázán na několik typů událostí zároveň. Každá z událostí odesílá informace o případu, produktech, dopravě a přidružené objednávce.

Formát dat

Webhook odesílá data ve formátu JSON. Data obsahují informaci o typu události (event_type), čas vytvoření (created_at) a data o případu, kterého se týkají (ticket).

{
  "event_type": "ticket.updated",
  "created_at": "2020-09-24T10:28:10.010Z",
  "ticket": {
    "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
    "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5",
    "owner": "e342f794-7b11-4acc-a46e-784a74a30af2",
    "state": "4531636a-108f-4ae3-abff-367901418600",
    "country": "CZ",
    "currency": "CZK",
    "customer": {
      "name": "Vladimír Remek",
      "email": "support@retino.io",
      "phone": "987654321"
    },
    "language": "cs",
    "order_id": "234567",
    "products": [
      {
        "id": "09c69980-299d-4d37-81d5-ed18c9565856",
        "ean": "",
        "name": "Apollo 11",
        "files": [],
        "price": {
          "vat": null,
          "with_vat": "990000000.0000",
          "without_vat": null
        },
        "amount": "1.0000",
        "serial": null,
        "variant": "XL",
        "category": "Rakety",
        "product_id": "#1",
        "manufacturer": "NASA",
        "custom_fields": {
          "1b8508b0-ba85-427c-b23c-ae739453b0cd": "74ea523e-ea95-44d4-85ff-758c485ff77d"
        },
        "bound_order_item": null
      }
    ],
    "shipping": [
      {
        "id": "2b20e85f-2201-494a-b3f9-85d89721174e",
        "files": [
          {
            "url": "https://retino-staging-files.s3.amazonaws.com/media/b58800a6-c095-4d47-b973-bc8248a95780/label_3824826667.pdf",
            "filename": "label_3824826667.pdf"
          }
        ],
        "status": "STATUS_ACCEPTED",
        "barcode": "Z3824826667",
        "history": [
          {
            "status": "STATUS_ACCEPTED",
            "created_at": "2020-09-24T12:28:08.075974+02:00"
          },
          {
            "status": "STATUS_INIT",
            "created_at": "2020-09-24T12:28:07.969356+02:00"
          }
        ],
        "created_at": "2020-09-24T12:28:07.958194+02:00",
        "updated_at": "2020-09-24T12:28:08.087506+02:00",
        "transport_id": "3824826667",
        "shipping_type": "e46e5f04-a4ab-413b-8279-cac83d39f39f",
        "shipping_provider": "ZASILKOVNA"
      }
    ],
    "closed_at": null,
    "is_unread": false,
    "created_at": "2020-09-24T11:30:53.210107+02:00",
    "order_date": "2020-09-09T00:00:00.000Z",
    "updated_at": "2020-09-24T12:28:09.988217+02:00",
    "bound_order": null,
    "custom_fields": {
      "resolve_by": "2020-10-08"
    },
    "customer_rating": null,
    "verification_state": "VERIFIED_AUTOMATICALLY",
    "customer_rating_comment": null
  }
}

Format dat případu (ticket) je totožný s modelem Ticket z Tickets API. Při každé události se odešle celá instance případu obsahující přidruženou objednávku, produkty a dopravu.

O doručování webhooků

Retino odesílá webhooky http metodou POST ve formátu JSON. Váš server musí být připraven příjmout tato data a odpovědět na ně v časovém limitu 10 sekund odpovědí se stavovým kódem <= 2xx (200, 201, …) (stavové kódy přesměrování 3xx nejsou akceptovány, protože jde o metodu POST).

Úspěsné doručení

Webhook bude úspěšně doručen, pokud:

• váš server odpoví v časovém limitu 10 sekund
• odpověď bude mít úspěšný stavový kód (2xx)

Opakování doručení

Pokud váš server neodpoví do 10 sekund, nebo odpoví chybovým stavovým kódem, doručení webhooku selže. Náš server se bude snažit doručit takový webhook v intervalu 72h s exponenciální prodlevou.

Pokud doručení jednoho webhooku nebude úspěšné ani po 72 hodinách od vytvoření, budeme vás informovat emailem a zašleme vám všechny relevantní informace.

Pokud během 72 hodin selžou všechny webhooky mířící na jeden endpoint, pak takový endpoint deaktivujeme a budeme vás o této události informovat emailem.