Receive Drime Sign events with webhooks

A webhook makes Drime call your server each time something happens to your signature requests. Every call is a JSON POST, signed with a secret so your server can check it comes from Drime.

#Add a webhook

1. Open Settings > Developers > Webhooks.

   From Sign, you can also click Preferences, open the Webhooks tab, then Open Developers settings.

2. Click Add webhook.

3. In Endpoint URL, enter the address of your server that receives the calls.

4. Under Events, set each event you want to receive to On, then click Create webhook.

   Webhook created confirms it.

5. Copy the secret now, then click Done.

   Webhook secret, copy it now: it is shown only once. Store it in a safe place.

#The events

#What Drime sends

Each call carries these headers:

• X-Drime-Event: the event, for example envelope.completed;

• X-Drime-Delivery: the number of the delivery;

• X-Drime-Signature: sha256= followed by the HMAC SHA-256 of the raw body, computed with your secret.

The JSON body holds event_type, event_uuid, timestamp and data, the document concerned with its signers. The Webhooks section shows a full example under Example request & signature verification.

A delivery can arrive more than once: use event_uuid to process each event only once.

#Check the signature

Compute the HMAC SHA-256 of the raw request body with your secret, then compare it with the X-Drime-Signature header. For example, 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));
}

Use the body exactly as received, before any JSON parsing.

#Test and follow the deliveries

• Send test sends a test event: Test event queued, check the deliveries log.

• Deliveries lists each call with its status: Success, Pending or Failed. Resend sends a delivery again.

• If your server does not answer or answers with an error, Drime tries again, up to 10 attempts over about 34 hours.

• The On / Off switch pauses a webhook without deleting it: Webhook paused confirms it, and Webhook enabled when you turn it back on.

#Change the secret or delete the webhook

• Rotate secret creates a new secret. The app warns: Rotate the secret? Your current secret will stop working immediately. Update your server right away.

• Delete removes the webhook: Delete this webhook and its delivery history?

#If it doesn't work

#Next steps

• Build an app or connect webhooks

• Create an API token

• What the audit certificate of a signed document contains