Webhooky

Pomocí webhooků mohou vaše externí aplikace reagovat například na změny stavu výjezdů nebo na přidání či úpravu jednotlivých entit (zákazníků, zařízení a podobně), bez nutnosti periodického dotazování a porovnávání dat.

Jak registrovat webhook

Nový webhook přidáte v Nastavení firmy - Integrace (uživatel musí mít roli administrátor).

Pro vytvoření nového webhooku musíte zadat URL adresu, na které bude váš webový server očekávat informace. mWork365 vám je v momentě vzniku události doručí pomocí POST HTTP požadavku. Obsah požadavku obvykle obsahuje identifikátory entit, kterých se událost týká. S jejich pomocí si můžete vyžádat potřebné informace standardní cestou přes naše API.

Dále musíte určit, které události chcete na dané URL adrese odebírat. Odebírat můžete i více různých událostí na jedné adrese, v takovém případě názvy událostí oddělte středníkem (;)

Volitelně zadáte Signature secret — klíč, kterým se doručovaná data podepisují (viz níže). Když pole necháte prázdné, klíč vygenerujeme automaticky.

Ověření podpisu

Každé doručení je podepsané — z těla požadavku spočítáme HMAC SHA-256 pomocí Signature secretu daného webhooku a výsledek pošleme v hlavičce X-Provider-Signature. Díky tomu si ověříte, že požadavek skutečně pochází z mWork365 a cestou se nezměnil.

Výpočet i postup ověření popisuje Podpis odchozích požadavků — stejný mechanismus platí i pro vlastní akční tlačítka.

Opakované doručení

Když vaše služba odpoví chybou nebo je nedostupná, doručení opakujeme — celkem až šestkrát, s rostoucími odstupy (1 s, 10 s, 1 min, 5 min a 30 min). Po vyčerpání pokusů se doručení vzdáváme.

Doručení je proto nejméně jednou, ne právě jednou — stejná událost může dorazit víckrát. Každé doručení nese hlavičku X-Provider-Event-Id se stabilním identifikátorem zdrojové události; ten se napříč opakováními nemění, takže podle něj duplicity spolehlivě odfiltrujete.

Poznámka

Odpovězte prosím co nejdříve (a zpracování si případně zařaďte do fronty na své straně). Pomalá odpověď se počítá jako neúspěšné doručení a spustí opakování.

Seznam podporovaných událostí

U každé události je uvedené schéma těla požadavku, které mWork365 odešle na vaši URL — hodnoty v ukázkách jsou datové typy, ne skutečná data.

Zákazníci

AddCustomer, EditCustomer, DeleteCustomer

{
    customerId: string(GUID),
    data: {
        name: string
    }
}

AddAddress, EditAddress, SetInvoiceAddress, SetContactAddress, DeleteAddress

{
    customerId: string(GUID),
    data: {
        id: string(GUID),
        address: string
    }
}

AddContactPerson, EditContactPerson, SetPrimaryContactPerson, DeleteContactPerson

{
    customerId: string(GUID),
    data: {
        id: string(GUID),
        firstName: string,
        lastName: string
    }
}

AddServiceObject, EditServiceObject, DeleteServiceObject, RevertMoveServiceObjectToCustomer

{
    customerId: string(GUID),
    serviceObjectId: string(GUID),
    data: {
        name: string
    }
}

MoveServiceObjectToCustomer

{
    customerId: string(GUID),
    serviceObjectId: string(GUID),
    data: {
        name: string,
        newCustomerName: string
    }
}

MoveServiceObjectFromCustomer

{
    customerId: string(GUID),
    serviceObjectId: string(GUID),
    data: {
        name: string,
        oldCustomerName: string
    }
}

Požadavky

AddOrderRequest, EditOrderRequest, DeleteOrderRequest, CompleteOrderRequest, CancelOrderRequest

{
    data: {
        orderRequestId: string(GUID),
        customerName: string
    }
}

Zakázky

AddOrder, AddOrderAuto, EditOrder, EditOrderByCustomer, CancelOrder, DeleteOrder, CompleteOrder, ReopenOrder

{
    customerId: string(GUID),
    orderId: string(GUID),
    data: {
        orderCode: string
    }
}

Výjezdy

PlanIntervention, ReplanIntervention, EditIntervention, StartDepartureForIntervention, StartIntervention, FinishIntervention, CompleteIntervention, CancelIntervention, DeleteIntervention, ResetInterventionState

{
    customerId: string(GUID),
    orderId: string(GUID),
    interventionId: string(GUID),
    data: {
        orderCode: string,
        day: string(Date),
        primaryAssigneeId: string(GUID),
        primaryAssigneeName: string,
        assignations: [
            {
                userId: string(GUID),
                plannedStart: string(DateTime)
                plannedEnd: string(DateTime)
            },
            ...
        ]
    }
}

Události

AddCalendarEvent, EditCalendarEvent, DeleteCalendarEvent

{
    data: {
        id: string(GUID),
        title: string
    }
}

Materiál a Sklady

AddMaterial, EditMaterial, DeleteMaterial

{
    materialId: string(GUID),
    data: {
        name: string
    }
}

AddStore, EditStore, DeleteStore

{
    storeId: string(GUID),
    data: {
        name: string
    }
}

AddToStore, RemoveFromStore, SetMaterialAmountInStore, RemoveDeletedMaterialFromStore

{
    materialId: string(GUID)
    storeId: string(GUID),
    data: {
        storeName: string,
        materialName: string,
        amount: decimal,
        amountText: string
    }
}

MoveFromStore, MoveToStore

{
    materialId: string(GUID)
    storeId: string(GUID),
    data: {
        fromStoreName: string,
        toStoreName: string,
        materialName: string,
        amount: decimal,
        amountText: string
    }
}

UseMaterialFromStore

{
    materialId: string(GUID)
    storeId: string(GUID),
    data: {
        storeName: string,
        materialName: string,
        amount: decimal,
        amountText: string,
        orderId: string(GUID),
        orderCode: string
    }
}