Webhooky — automatická hlášení změn stavu dokumentu

Místo opakovaného dotazování na stav dokumentu si nechte změny hlásit automaticky: Signi zavolá adresu ve vaší aplikaci, jakmile dokument změní stav. Tomu se říká webhook.

Jak webhook nastavit

Webhooky se zadávají při zakládání dokumentu, v JSON pokynech (jen u hlavního dokumentu, ne u příloh):

{
    "people": [ ... ],
    "file": "uploaded_file_key",
    "webhooks": [
        { "state": "completed", "url": "https://vase-aplikace.cz/signi-hotovo" },
        { "state": "rejected",  "url": "https://vase-aplikace.cz/signi-odmitnuto" }
    ]
}

Volaná adresa může být pro všechny stavy stejná — který stav nastal, poznáte z pole state v příchozích datech.

Hlásit jde přechod do stavů pending, completed, rejected a expired — co znamenají, najdete v článku Životní cyklus dokumentu.

Co vám přijde

Signi na vaši adresu pošle POST požadavek s informacemi o dokumentu:

{
    "contract_id": 1,
    "state": "completed",
    "file": "__TEMPORARYURL__",
    "attachments": [
        { "contract_id": 2, "state": "completed", "file": "__TEMPORARYURL__" }
    ]
}

• contract_id — ID dokumentu (stejné, jaké jste dostali při založení).
• state — stav, do kterého dokument přešel.
• file — dočasná adresa ke stažení PDF; platí 10 minut — viz Stažení PDF z odkazu ve webhooku.
• attachments — totéž pro přílohy dokumentu.

Když webhook neprojde

• Doručení opakujeme automaticky. Když vaše adresa neodpoví (nedostupný server, chyba 5xx), Signi volání zopakuje celkem třikrát: první opakování po 5 sekundách, druhé po dalších 10 a třetí po dalších 20 sekundách. Pokud neuspěje ani poslední pokus, další se už nekoná; stav dokumentu si můžete kdykoli zjistit dotazem na jeho detail.
• Adresa musí být veřejně dosažitelná (HTTPS). Neplatná adresa vrátí při zakládání chybu „Webhook is invalid".
• Nepovolený stav vrátí „Webhook state [state] is not allowed" — viz Chyby a jejich řešení.

Kam dál

• Životní cyklus dokumentu
• Stažení PDF z odkazu ve webhooku
• E-mailové notifikace — upozornění e-mailem podepisujícím (místo zpráv pro váš systém)
• Quickstart — první dokument k podpisu přes API