Webhooky představují nejefektivnější způsob, jak v reálném čase sledovat události v DigiSignu, jako je dokončení podpisu obálky nebo změna stavu příjemce. Místo neustálého dotazování (pollingu) na stav obálky zašle DigiSign automatický HTTP POST požadavek na vaši serverovou adresu ve chvíli, kdy daná událost nastane.
1. Registrace Webhooku přes API
Pro vytvoření nového webhooku použijte endpoint /api/webhooks.
Endpoint: POST /api/webhooks
Příklad requestu:
{
"event": "envelopeCompleted",
"url": "https://vasedomena.cz/api/webhook-prijem",
"status": "enabled"
}
Sledované eventy nad obálkou
Sledované eventy nad obálkou
envelopeSent | obálka odeslána |
envelopeCompleted | obálka dokončena (podepsána všemi podepisujícími) |
envelopeExpired | obálka expirovala |
envelopeDeclined | obálka byla odmítnuta (podepisujícím) |
envelopeDisapproved | obálka byla zamítnuta (schvalovatelem) |
envelopeCancelled | obálka byla zrušena |
envelopeDeleted | obálka byla smazána |
recipientSent | obálka byla odeslána příjemci |
recipientDelivered | příjemce otevřel obálku (proklik odkaz z emailu) |
recipientNonDelivered | příjemci se nepodařilo obálku doručit (např. chybná adresa) |
recipientAuthFailed | příjemce vyčerpal 3 pokusy na autentizaci |
recipientSigned | příjemce podepsal všechny dokumenty v obálce |
recipientDownloaded | příjemce si stáhnul hotovou obálku |
recipientDeclined | příjemce odmítl podepsání obálky (podepisující) |
recipientDisapproved | příjemce zamítl schválení obálky (schvalovatel) |
recipientCanceled | příjemce byl zrušen |
kompletní seznam najdete v API dokumentaci u endpointu /api/webhooks
Zabezpečení pomocí OAuth 2.0
Zabezpečení pomocí OAuth 2.0
Pokud váš přijímací server (webhook listener) vyžaduje autorizaci pomocí OAuth 2.0, DigiSign podporuje automatické získávání a obnovování přístupových tokenů (Access Tokens). Při registraci nebo aktualizaci webhooku stačí v těle požadavku zaslat konfigurační údaje pro vaši autorizační autoritu.
Konfigurační parametry
Pro aktivaci OAuth zabezpečení přidejte do JSON payloadu následující pole:
oAuthTokenEndpoint: URL adresa vašeho autorizačního serveru, kde DigiSign požádá o token.
oAuthClientId: Identifikátor klienta (Client ID) přidělený DigiSignu.
oAuthClientSecret: Tajný klíč (Client Secret) pro autentizaci.
oAuthScopes (volitelné): Pole řetězců definující požadovaný rozsah oprávnění (např.
["read", "write"]).oAuthIntrospectEndpoint (volitelné): URL adresa pro introspekci tokenu. Toto pole slouží k ověření stavu a metadat aktivního přístupového tokenu (dle RFC 7662). DigiSign tento endpoint využije pro validaci integrity spojení v rámci pokročilých bezpečnostních scénářů.
Příklad registrace webhooku s OAuth:
{
"event": "envelopeSent",
"url": "https://vasedomena.cz/api/webhook",
"status": "enabled",
"oAuthTokenEndpoint": "https://auth.vasedomena.cz/token",
"oAuthIntrospectEndpoint": "https://auth.vasedomena.cz/introspect",
"oAuthClientId": "b4585ce5-e853-47e0-965d-c2472da25d31",
"oAuthClientSecret": "312c10b883894bb095df69fa454621dc",
"oAuthScopes": ["read"]
}Jak proces probíhá?
Získání tokenu: Před odesláním události DigiSign provede POST požadavek na váš
oAuthTokenEndpoints údaji Client ID a Secret (v režimu client_credentials).Autorizace požadavku: Získaný Access Token následně DigiSign přiloží ke každému requestu na vaši webhook URL v hlavičce
Authorization: Bearer {token}.Správa tokenu: DigiSign si token ukládá a používá jej opakovaně, dokud nevyprší jeho platnost. Poté automaticky požádá o nový.
💡Tip pro vývojáře: Při použití OAuth 2.0 doporučujeme i nadále provádět Kontrolu podpisu Webhook requestů (viz sekce 3), abyste měli jistotu, že požadavek skutečně odeslal systém DigiSign.
2. Struktura odchozího požadavku
DigiSign odesílá data ve formátu JSON s hlavičkou Content-Type: application/json. Každý request obsahuje identifikátor události, čas vzniku a data příslušné entity (obálky či příjemce).
Příklad dat zasílaných DigiSignem:
{
"id": "3974d252-b027-46df-9fd8-ddae54bc9ab9",
"event": "envelopeCompleted",
"name": "envelope.completed",
"time": "2026-02-14T14:07:23+02:00",
"entityName": "envelope",
"entityId": "4fcf171c-4522-4a53-8a72-784e1dd36c2a",
"data": {
"status": "completed"
},
"envelope": {
"id": "4fcf171c-4522-4a53-8a72-784e1dd36c2a",
"status": "completed"
}
}
Pro testování volání URL webhooku lze použít Test Webhook endpoint:
POST /api/webhooks/3974d252-b027-46df-9fd8-ddae54bc9ab9/test
Aby DigiSign považoval doručení za úspěšné, musí váš server vrátit HTTP kód 2xx do 5 sekund. Jakýkoliv jiný kód bude brán jako neúspěšné zpracování a událost se zařadí k opakování pokusu.
3. Kontrola podpisu a zabezpečení
Pro zajištění, že požadavek skutečně přišel z DigiSignu a nebyl po cestě změněn, doporučujeme ověřovat podpisovou hlavičku Signature.
V každém reqestu pak DigiSign posílá hlavičku Signature která obsahuje časové razítko a podpisový hash. Hlavička vypadá nějak takto:
Signature: t=1623134422,s=b15109ca56aadb4d87efdb03d258dbe40eb...
Postup ověření:
Získání secretu: Přes API si u daného webhooku zjistěte jeho unikátní
secret.Parsování hlavičky: Hlavička má formát
t={timestamp},s={hash}.Kontrola stáří: Pokud je timestamp starší než 5 minut, požadavek ignorujte (ochrana proti replay útokům).
Výpočet HMAC: Vypočítejte HMAC s funkcí SHA256. Jako klíč použijte
secreta jako data řetězec ve formátu{timestamp}.{requestBody}.Porovnání: Vypočtený hash se musí shodovat s hodnotou
sv hlavičce.
Příklad v PHP
<?php
$header = $_SERVER['HTTP_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');
$secret = 'your-webhook-secret';
if (preg_match('/t=(?<t>\d+),s=(?<s>\w+)/', $header, $matches) !== 1) {
throw new Exception('Unable to parse signature header');
}
$ts = (int)($matches['t'] ?? 0);
$signature = $matches['s'] ?? '';
if ($ts < (time() - 300)) {
throw new Exception('Request is older than 5 minutes');
}
$expected = hash_hmac('sha256', $ts . '.' . $payload, $secret);
if (hash_equals($expected, $signature) === false) {
throw new Exception('Invalid signature');
}
echo "Webhook event received" . PHP_EOL;
echo $payload;
4. Retry logika a pokusy o volání
Pokud váš server neodpoví úspěšně, DigiSign provede až 12 pokusů o doručení v exponenciálních intervalech:
Pokus | 1 | 2 | 3 | 4 | 5 | 6 - 12 |
Interval dalšího pokusu | 5 min | 10 min | 30 min | 1 hod | 2 hod | 24 hod |
Pokud při pokusu o volání bude webhook pozastavený nebo smazaný, tak už další neproběhnou. Jestliže ale pozastavíte a obnovíte webhook předtím, než proběhl další pokus, pokusy budou pokračovat.
Stav pokusů můžete sledovat na zdroji WebhookAttempt přes endpointy:
GET /api/webhooks/{webhookID}/attempts
GET /api/webhooks/{webhookID}/attempts/{webhookAttemptID}.
Neúspěšný pokus lze také manuálně opakovat pomocí endpointu POST /api/webhooks/{webhookID}/attempts/{webhookAttemptID}/resend
5. Idempotence (Duplicitní zpracování)
V ojedinělých případech může být stejná událost doručena vícekrát (např. při timeoutu sítě). Doporučujeme na vaší straně implementovat kontrolu pomocí id události a již zpracované identifikátory ignorovat.