Webhooky umožňují nastavit si vlastní URL, kterou DigiSign provolá ve chvíli, kdy nastane určitá událost. Toto stačí nastavit jednou a URL bude volána pro všechny následné události.
Webhook události u obálky:
envelopeSent | obálka odeslána |
envelopeCompleted | obálka dokončena (podepsána všemi podepisujícími) |
envelopeExpired | obálka expirovala |
envelopeCancelled | obálka byla zrušena |
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 |
kompletní seznam najdete v API dokumentaci u endpointu /api/webhooks
Registrace Webhooku přes API
Přidání webhooku lze provést přes zdroj Webhook.
POST /api/webhooks
{
"event": "envelopeCompleted",
"url": "https://my-api.example.com/api/envelope/completed"
}
Ve chvíli kdy nastane daná událost, DigiSign odešle následující request:
POST https://my-api.example.com/api/envelope/completed
Content-Type: application/json
{
"id": "3974d252-b027-46df-9fd8-ddae54bc9ab9", // id události
"event": "envelopeCompleted", // webhook události
"name": "envelope.completed", // název události
"time": "2021-06-07T14:07:23+02:00", // čas události
"entityName": "envelope", // název entity
"entityId": "4fcf171c-4522-4a53-8a72-784e1dd36c2a", // id entity
"data": { // data události
"status": "completed" // liší se podle entity
},
"envelope": { // stará struktura
"id": "3974d252-b027-46df-9fd8-ddae54bc9ab9",
"status": "completed"
}
}
Pro testování volání URL webhooku lze použít Test Webhook endpoint:
POST /api/webhooks/3974d252-b027-46df-9fd8-ddae54bc9ab9/test
Chcete-li potvrdit přijetí události, musí váš webhook vrátit 2xx stavový kód HTTP. Jakýkoliv jiný kód bude brán jako neúspěšné zpracování a událost se zařadí k opakování pokusu. Stejně tak pokud váš endpoint neodpoví do 5s (timeout).
Pokusy volání Webhooku
Pokud pokus o doručení webhooku skončí neúspěšně, tak budeme provolání zkoušet znovu v této exponenciální sekvenci (max 12 pokusů):
Pokus | 1 | 2 | 3 | 4 | 5 | 6 - 12 |
další za | 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.
Na zdroji WebhookAttempt lze vypsat všechny pokusy včetně jejich odpovědí.
GET /api/webhooks/3974...9ab9/attempts
GET /api/webhooks/3974...9ab9/attempts/3974...9ab9
Pokus lze i manuálně opakovat přes resend
POST /api/webhooks/3974...9ab9/attempts/3974...9ab9/resend
Duplicitní zpracování události
Může se stát, že váš webhook dostane stejnou událost vícekrát než jednou. Doporučujeme chránit se před duplicitním zpracováním událostí tím, že jej uděláte idempotentní. Jedním ze způsobů, jak to udělat, je ukládání ID událostí, které jste zpracovali, a ty pak při dalším přijetí ignorovat.
Kontrola podpisu Webhook requestů
Pokud si chcete být jistí, že requesty na váš Webhook opravdu chodí z DigiSign a že nikdo nezměnil jejich obsah, můžete si to ověřit pomocí podpisové hlavičky (Signature).
Přes API si můžete u Webhooku zjistit secret který se používá jako klíč.
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...
Pro ověření podpisu:
Extrahujte časové razítko a podpis z hlavičky t={timestamp},s={signature}
Ověřte stáří časového razítka, pokud je časové razítko starší jak 5 minut tak se může jednat o Replay attack, takový request nezpracovávejte.
Vytvořte si základ podpisu {timestamp}.{requestBody}
skládá se z časového razítka (z hlavičky), tečky, a těla requestu
Např: 1623134422.{"id": "3974d252-b027-46df-9fd8-ddae54bc9ab9",...}
Ze základu podpisu vypočítejte HMAC s hashovací funkcí SHA256, jako klíč použijte secret webhooku.
Porovnejte shodu mezi vypočítaným podpisem a podpisem z hlavičky.
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;
Zabezpečení OAuth
Webhooky je možné zabezpečit pomocí OAuth 2.0. Při registraci či updateu webhooku stačí v těle navíc poslat údaje pro OAuth:
oAuthTokenEndpoint
oAuthClientId
oAuthClientSecret
Případně je možné volitelně rozšířit o scopes:
POST /api/webhooks
{
"event": "envelopeSent",
"url": "https://my-api.example.com/api/envelope/completed",
"status": "enabled",
"oAuthTokenEndpoint": "https://my-api.example.com/api/envelope/completed",
"oAuthClientId": "b4585ce5-e853-47e0-965d-c2472da25d31",
"oAuthClientSecret": "312c10b883894bb095df69fa454621dc",
"oAuthScopes":[ "read" ]
}
Automatická deaktivace webhooku
Pokud uživatelům dlouhodobě neprochází zadané webhooky, zasíláme nyní nejprve upozornění o možné deaktivaci tohoto webhooku s výzvou k opravě.
Pokud i následujících 7 dní po odeslání upozornění nebylo úspěšně doručeno více než 75% událostí webhooku, bude tento webhook automaticky deaktivován a uživateli odeslán email s informací o provedené deaktivaci.
Podmínky pro deaktivace webhooku:
Za posledních 7 dní se nepodařilo doručit více než 75 % událostí.
Datum vytvoření webhooku je starší než 7 dní
Registrace Webhooku přes Selfcare
Administrátoři organizace mohou webhooky zaregistrovat v selfcare v Nastavení> Pro vývojáře> Webhooky.
Kliknutím na tlačítko Nový webhook se otevře dialogové okno, pro zadání údajů webhooku. Při zaškrtnutí možnosti Zabezpečit pomocí OAuth 2.0 se objeví další pole:
