Webhooky

Webhooky jsou způsob, jak získávat upozornění z Retina o různých událostech v reálném čase. Místo periodického dotazování API si můžete vytvořit webhook a Retino vám bude automaticky zasílat informace o změnách na vámi určenou URL adresu.

Pro informace o webhooku shipping.ordered se podívejte na článek Webhook o objednání dopravy.

Vytvoření webhooku

1. Připravte na vašem serveru URL endpoint pro příjem webhooků (např. vas-eshop.cz/webhook-retino)
2. Přejděte do Nastavení > API > Webhooky v Retinu
3. Klikněte na "Vytvořit webhook"
4. Zadejte URL adresu vašeho endpointu
5. Vyberte události, které chcete odebírat
6. Uložte nastavení

Webhooky se nastavují na úrovni celého účtu a nejsou omezeny na jednotlivé uživatele. Po vytvoření webhooku můžete odeslat testovací událost z detailu webhooku pro ověření správné konfigurace.

Zabezpečení

Každý webhook obsahuje v hlavičce požadavku autentifikační token pro ověření, že požadavek skutečně pochází z Retina:

X-Retino-Secret: <token>

Tento token naleznete v nastavení jednotlivých webhooků. Při příjmu webhooků byste měli vždy ověřit, že hlavička obsahuje správný token, který odpovídá vašemu webhooku.

Obnovení tajného tokenu

POZOR! Pokud obnovíte token webhooku, váš server nebude schopen přijímat webhooky, dokud nový token neimplementujete na vaší straně.

HTTPS

Důrazně doporučujeme, aby komunikace probíhala přes šifrovaný protokol HTTPS. Pokud váš webhook používá nezabezpečený protokol HTTP, Retino vás na toto riziko upozorní v nastavení.

Typy událostí pro případy

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.

Vzorová data pro jednotlivé události

ticket.created / ticket.updated

Odesláno při vytvoření nebo změně případu.

{
  "event_type": "ticket.created",
  "created_at": "2020-09-24T10:28:10.010Z",
  "ticket": {
    "id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
    "code": "20210001",
    "state": "4531636a-108f-4ae3-abff-367901418600",
    "tags": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "type": "44c88eec-b995-4c84-b269-2ff06c8fe5d5",
    "owner": "e342f794-7b11-4acc-a46e-784a74a30af2",
    "bound_order": null,
    "customer": {
      "name": "Vladimír Remek",
      "email": "support@retino.com",
      "phone": "987654321"
    },
    "currency": "CZK",
    "language": "cs",
    "country": "CZ",
    "order_id": "234567",
    "order_date": "2020-09-09T00:00:00.000Z",
    "customer_rating": null,
    "customer_rating_comment": null,
    "custom_fields": {
      "resolve_by": "2020-10-08"
    },
    "verification_state": "VERIFIED_AUTOMATICALLY",
    "is_unread": false,
    "created_at": "2020-09-24T11:30:53.210107+02:00",
    "updated_at": "2020-09-24T11:30:53.525472+02:00",
    "closed_at": null
  }
}

ticket.product.created / ticket.product.updated

Odesláno při přidání nebo úpravě produktu v případu.

{
  "event_type": "ticket.product.created",
  "created_at": "2020-09-24T10:28:10.010Z",
  "ticket_id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
  "product": {
    "id": "09c69980-299d-4d37-81d5-ed18c9565856",
    "bound_order_item": null,
    "price": {
      "with_vat": "990000000.0000",
      "without_vat": null,
      "vat": null
    },
    "files": [],
    "name": "Apollo 11",
    "manufacturer": "NASA",
    "category": "Rakety",
    "product_id": "#1",
    "variant": "XL",
    "ean": "",
    "serial": null,
    "amount": "1.0000",
    "custom_fields": {
      "1b8508b0-ba85-427c-b23c-ae739453b0cd": "74ea523e-ea95-44d4-85ff-758c485ff77d"
    }
  }
}

ticket.shipping.created / ticket.shipping.updated

Odesláno při vytvoření nebo aktualizaci dopravy.

{
  "event_type": "ticket.shipping.created",
  "created_at": "2020-09-24T10:28:10.010Z",
  "ticket_id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
  "shipping": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "vendor_id": "PPL",
    "shipping_type": "Parcel",
    "state": "WAITING_FOR_PICKUP",
    "trace_url": "http://example.com/tracking/123",
    "sender": {
      "name": "Vladimír Remek",
      "email": "support@retino.com",
      "phone": "987654321",
      "address": {
        "street": "Kosmonautů 10",
        "city": "Praha",
        "zip": "16000",
        "country": "CZ"
      }
    },
    "recipient": {
      "name": "Váš e-shop",
      "email": "eshop@example.com",
      "phone": "123456789",
      "address": {
        "street": "Hlavní 123",
        "city": "Praha",
        "zip": "11000",
        "country": "CZ"
      }
    },
    "created_at": "2020-09-24T10:28:10.010Z",
    "updated_at": "2020-09-24T10:28:10.010Z"
  }
}

ticket.refund.created / ticket.refund.updated

Odesláno při vytvoření nebo aktualizaci refundace.

{
  "event_type": "ticket.refund.created",
  "created_at": "2020-09-24T10:28:10.010Z",
  "ticket_id": "8fad1c8d-3740-4aab-a224-c0ef379ea216",
  "refund": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "amount": "990000000.0000",
    "currency": "CZK",
    "state": "WAITING_FOR_APPROVAL",
    "type": "BANK_ACCOUNT",
    "bank_account": {
      "account_number": "123456789/1010",
      "iban": "CZ1234567890123456789012",
      "bic": "GIBACZPX"
    },
    "created_at": "2020-09-24T10:28:10.010Z",
    "updated_at": "2020-09-24T10:28:10.010Z"
  }
}

Implementace příjmu webhooků

Pro příjem webhooků musíte na vašem serveru implementovat endpoint, který bude zpracovávat HTTP POST požadavky. Zde je jednoduchý příklad implementace v Node.js:

const express = require('express');
const bodyParser = require('body-parser');
const app = express();

app.use(bodyParser.json());

app.post('/webhook-retino', (req, res) => {
  // Kontrola tajného tokenu
  const token = req.headers['x-retino-secret'];
  if (token !== 'váš_tajný_token') {
    return res.status(403).send('Neplatný token');
  }

  // Zpracování události
  const event = req.body;
  console.log(`Přijata událost: ${event.event_type}`);

  // Zde zpracujte data podle typu události
  switch (event.event_type) {
    case 'ticket.created':
      // Zpracování vytvoření případu
      console.log(`Vytvořen nový případ: ${event.ticket.code}`);
      break;
    case 'ticket.product.created':
      // Zpracování přidání produktu
      console.log(`Přidán produkt do případu: ${event.product.name}`);
      break;
    // další typy událostí...
  }

  // Odpověď serveru
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Server pro příjem webhooků běží na portu 3000');
});

Osvědčené postupy

1. Verifikace tokenu - Vždy ověřujte token v hlavičce X-Retino-Secret pro zajištění bezpečnosti
2. Rychlá odpověď - Odpovídejte na webhook co nejrychleji (ideálně do 5 sekund) a složitější zpracování provádějte asynchronně
3. Ošetření chyb - Implementujte robustní ošetření chyb, aby váš endpoint byl odolný vůči neplatným datům
4. Logování - Zaznamenávejte přijaté webhooky pro pozdější analýzu a ladění
5. Idempotence - Navrhněte zpracování webhooků tak, aby bylo idempotentní (opakované zpracování stejné události nezpůsobí problémy)

Testování webhooků

Pro testování webhooků můžete využít následující možnosti:

1. Použít službu jako webhook.site nebo requestbin.com pro zachycení a inspekci webhook požadavků
2. Využít lokální tunelování pomocí nástrojů jako ngrok pro testování webhooků na vašem lokálním vývojovém prostředí
3. Odeslat testovací událost přímo z detailu webhooku v administraci Retina

Pro více informací o dalších možnostech integrace s Retinem navštivte dokumentaci Tickets API.