Docs
Webhooks

Webhooks

Notifiy your applications about document events.

What is a webhook?

DigiSign uses webhooks to push real-time notifications to you about your documents. All webhooks use HTTPS and deliver a JSON payload that can be used by your application. You can use webhook feeds to do things like:

  • Automatically approve your customers' requests (waiting on their signatures)
  • Call actions in your own app based on event types
  • Store all events in your own database for custom reporting/retention

Steps to receive a webhook

You can start receiving real-time events in your app using the steps:

  1. Create a local endpoint to receive requests
  2. Register your development webhook endpoint
  3. Test that your webhook endpoint is working properly
  4. Deploy your webhook endpoint to production
  5. Register your production webhook endpoint

1. Create a local endpoint to receive requests

In your local application, create a new route that can accept POST requests.

  const express = require('express');
  const app = express();
  const port = 3000; // You can choose any port you prefer
 
  // Define a simple route
  app.post('/app', (req, res) => {
      // Do something with the request.body
      res.send('Hello, World!');
  });
 
  // Start the server
  app.listen(port, () => {
      console.log(`Server is running on http://localhost:${port}`);
  });

On receiving an event, you should respond with an HTTP 200 OK to signal to DigiSign that the event was successfully delivered.

2. Register your development webhook endpoint

Register your publicly accessible HTTPS URL in the Resend dashboard.

3. Test that your webhook endpoint is working properly

Send a few test documents and sign them to check that your webhook endpoint is receiving the events.

4. Deploy your webhook endpoint

After you’re done testing, deploy your webhook endpoint to production.

​

5. Register your production webhook endpoint

Once your webhook endpoint is deployed to production, you can register it in the DigiSign dashboard.


Event Types

List of supported event types and their payload.

document.sent

The document has been sent to your recipients.

  • The event_data.recipient object contains the email address, name, and form data of the recipient who received the document.
  • The event_data.request.public_id is the unique identifier of the document that was sent.
  • The event_data.request.message.subject is the subject of the document that was sent.
  • The event_data.request.link is the URL to the document that was sent.
  • The event_data.auth_code is the authentication code for the document that was sent.
{
  "type": "document.sent",
  "event_data": {
    "recipient": {
      "email": "james@example.com",
      "name": "James Martin"
    },
    "request": {
      "public_id": "f30f74f****************0ccaa59",
      "message": {
        "subject": "Sign with Digisign (Demo 2)"
      }
    },
    "link": "[SIGNING_URL]",
    "auth_code": "b358ce8**************a6171",
    "auth_link": "[AUTH_URL]"
  },
  "workspace": "7ae4418************414a67",
  "organisation": "9234a4****************b696c77f4"
}

document.signed

Your recipient successfully reviewed and signed your document.

  • The event_data.recipient object contains the email address, name, and form data of the recipient who signed the document.
  • The event_data.request.public_id is the unique identifier of the document that the recipient signed.
  • The event_data.signature is the signature of the recipient.
  • The event_data.validation_link is the URL to validate the signature.
  • The event_data.validation_link_image is the URL to the image of the signature.
{
  "type": "document.signed",
  "event_data": {
    "recipient": {
      "email": "james@example.com",
      "name": "James Martin",
      "form_data": {
        "user_biometric_id": "65***************41",
        "user_biometric_type": "nin.ng"
      },
      "validation_link": "[VALIDATION_URL]",
      "validation_link_image": "[ASSET_URL]"
    },
    "request": {
      "public_id": "f30f74******************ccaa59",
      "message": {
        "subject": "Sign with Digisign (Demo 2)"
      }
    },
    "signature": "[SIGNATURE]"
  },
  "workspace": "7ae441**************2414a67",
  "organisation": "9234a4**************96c77f4"
}

document.completed

Every recipient in your document has signed your document and DigiSign changed its status to completed.

{
  "type": "document.completed",
  "event_data": {
    "request": "4315fd3**************edbe030ce",
    "recipients": [
      {
        "email": "james@example.com",
        "name": "James Martin",
        "public_id": "a7512d0*****************9ba7124a",
        "form_data": {
          "user_biometric_id": "67***********90",
          "user_biometric_type": "nin.ng"
        }
      }
    ],
    "envelope": {
      "public_id": "dd85a4*****************e5f12c",
      "signature": "[UNIQUE_SIGNATURE]",
      "attachments": [
        "[ATTACHMENT_URL]"
      ],
      "validation_link": "[VALIDATION_URL]",
      "validation_link_image": "[ASSET_URL]"
    }
  },
  "workspace": "20a888b********************be4b",
  "organisation": "5d9ec********************16f70"
}

document.rejected

A recipient in your request has rejected your document and DigiSign changed its status to rejected.

{
  "recipient": {
    "email": "jane.doe@example.com",
    "name": "Jane Doe"
  },
  "request": {
    "public_id": "129800c**************a9c5",
    "message": {
      "subject": "Sign With DigiSign (Test)"
    }
  },
  "rejection_reason": {
    "value": "**REASON**",
    "date": "2025-03-21T14:54:42.151Z"
  },
  "workspace": "7ae441**************2414a67",
  "organisation": "9234a4**************96c77f4"
}

alert.do_not_trust

Sent after DigiSign detects a suspicious/fraudulent document signature.

  • The event_data.files array contains the URLs of the images that DigiSign has detected as suspicious.
  • The event_data.recipient object contains the email address and name of the recipient who signed the document.
  • The event_data.request.public_id is the unique identifier of the document that DigiSign has detected as suspicious.
{
  "type": "alert.do_not_trust",
  "event_data": {
    "files": [
      "[ASSET_URL]",
      "[ASSET_URL]"
    ],
    "recipient": {
      "email": "james@example.com",
      "name": "James Martin"
    },
    "request": {
      "public_id": "f30f74f**************6c0ccaa59",
      "message": {
        "subject": "Sign with Digisign (Demo 2)"
      }
    },
    "envelope": {
      "public_id": "dd85a4*****************e5f12c",
      "signature": "[UNIQUE_SIGNATURE]",
      "attachments": [
        "[ATTACHMENT_URL]"
      ],
      "validation_link": "[VALIDATION_URL]",
      "validation_link_image": "[ASSET_URL]"
    }
  },
  "workspace": "7ae441************2414a67",
  "organisation": "9234a**************b696c77f4"
}

FAQ

API KeysExamples