Events van Drime Sign ontvangen met webhooks

Met een webhook roept Drime je server aan telkens als er iets gebeurt met je ondertekeningsverzoeken. Elke oproep is een JSON-POST, ondertekend met een secret zodat je server kan controleren dat die van Drime komt.

#Een webhook toevoegen

1. Open Instellingen > Ontwikkelaars > Webhooks.

   Vanuit Sign kun je ook op Voorkeuren klikken, het tabblad Webhooks openen en daarna Ontwikkelaarsinstellingen openen kiezen.

2. Klik op Webhook toevoegen.

3. Vul bij Endpoint-URL het adres in van je server die de oproepen ontvangt.

4. Zet onder Events elk event dat je wilt ontvangen op Aan en klik daarna op Webhook maken.

   Webhook aangemaakt bevestigt het.

5. Kopieer nu het secret en klik op Klaar.

   Webhook-secret, kopieer het nu: het wordt maar één keer getoond. Bewaar het op een veilige plek.

#De events

#Wat Drime verstuurt

Elke oproep bevat deze headers:

• X-Drime-Event: het event, bijvoorbeeld envelope.completed;

• X-Drime-Delivery: het nummer van de bezorging;

• X-Drime-Signature: sha256= gevolgd door de HMAC SHA-256 van de ruwe body, berekend met je secret.

De JSON-body bevat event_type, event_uuid, timestamp en data, het betrokken document met zijn ondertekenaars. Het onderdeel Webhooks toont een volledig voorbeeld onder Voorbeeldverzoek & handtekeningverificatie.

Een bezorging kan meer dan eens aankomen: gebruik event_uuid om elk event maar één keer te verwerken.

#De handtekening controleren

Bereken met je secret de HMAC SHA-256 van de ruwe body van het verzoek en vergelijk die met de header X-Drime-Signature. Bijvoorbeeld in Node.js:

import crypto from 'node:crypto';

function isFromDrime(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Gebruik de body precies zoals ontvangen, vóór elke JSON-verwerking.

#Testen en de bezorgingen volgen

• Test versturen stuurt een test-event: Test-event in de wachtrij gezet, bekijk het bezorglogboek.

• Bezorgingen toont elke oproep met de status: Succes, In afwachting of Mislukt. Opnieuw versturen stuurt een bezorging nog een keer.

• Antwoordt je server niet of met een fout, dan probeert Drime het opnieuw, tot 10 pogingen over ongeveer 34 uur.

• De schakelaar Aan / Uit pauzeert een webhook zonder hem te verwijderen: Webhook gepauzeerd bevestigt het, en Webhook ingeschakeld als je hem weer aanzet.

#Het secret wijzigen of de webhook verwijderen

• Geheim vernieuwen maakt een nieuw secret. De app waarschuwt: Het secret vernieuwen? Je huidige secret werkt onmiddellijk niet meer. Werk je server meteen bij.

• Verwijderen verwijdert de webhook: Deze webhook en de bezorggeschiedenis verwijderen?

#Als het niet lukt

#Volgende stappen

• Een app bouwen of webhooks instellen

• Een API-token maken

• Wat het auditcertificaat van een ondertekend document bevat