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.
Poznámka: Webhooky jsou prémiová funkcionalita, která je součástí rozšíření "API & Webhooky". Pokud máte toto rozšíření aktivní, naleznete nastavení webhooků v Nastavení > API > Webhooky.
Pro informace o webhooku shipping.ordered se podívejte na článek Webhook o objednání dopravy.
Vytvoření webhooku
Připravte na vašem serveru URL endpoint pro příjem webhooků (např.
vas-eshop.cz/webhook-retino)Přejděte do Nastavení > API > Webhooky v Retinu
Klikněte na "Vytvořit webhook"
Zadejte URL adresu vašeho endpointu
Vyberte události, které chcete odebírat
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.
Událost | Popis |
| Vytvoření nového případu |
| Jakákoliv úprava případu |
| Vytvoření nového produktu v případu |
| Úprava produktu v případu |
| Vytvoření nové dopravy v případu |
| Úprava dopravy nebo aktualizace stavu |
| Vytvoření refundace |
| Úprava refundace |
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": "[email protected]",
"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": "[email protected]",
"phone": "987654321",
"address": {
"street": "Kosmonautů 10",
"city": "Praha",
"zip": "16000",
"country": "CZ"
}
},
"recipient": {
"name": "Váš e-shop",
"email": "[email protected]",
"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
Verifikace tokenu - Vždy ověřujte token v hlavičce X-Retino-Secret pro zajištění bezpečnosti
Rychlá odpověď - Odpovídejte na webhook co nejrychleji (ideálně do 5 sekund) a složitější zpracování provádějte asynchronně
Ošetření chyb - Implementujte robustní ošetření chyb, aby váš endpoint byl odolný vůči neplatným datům
Logování - Zaznamenávejte přijaté webhooky pro pozdější analýzu a ladění
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:
Použít službu jako webhook.site nebo requestbin.com pro zachycení a inspekci webhook požadavků
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í
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.