Setup webhooks

To receive real-time notifications about events in your account, you can set up webhooks. Webhooks allow your application to be notified when specific events occur, such as document signing or verification completion.

Create a webhook endpoint

First, create an endpoint in your application that can receive HTTP POST requests. This endpoint will handle incoming webhook notifications.

Make sure your endpoint is publicly accessible and can handle incoming POST requests. It must also have a valid SSL certificate (HTTPS).

Register your webhook endpoint

Next, register your webhook endpoint by providing the URL of your endpoint.

You can register your webhook endpoint by calling events/endpoints/set or within the iinked Sign web application under Settings > Integrations > Endpoints.

Authenticate requests (optional)

Optionally, update your webhook endpoint to authenticate requests using a secret token. This helps ensure that incoming requests are from the iinked Sign platform.

Create endpoint via iinked Sign

You can manually configure your webhook endpoint within the iinked Sign platform. To do this, navigate to Settings > Integrations > Endpoints in the web application. From there, you can add one or more endpoints by providing the URL of your webhook endpoint.

Create endpoint via API

To help streamline the process of setting up webhooks, you can use the events/endpoints/set endpoint to register your webhook URL.

When called with OAuth authorization, this endpoint is useful to create, update, or delete a webhook endpoint for the users account, overwriting any existing endpoint associated to your OAuth client ID.The endpoint will automatically be named after your application name as defined when registering your client ID.

Request

POST /events/endpoints/set
{
    "url": "https://example.com/your-webhook-endpoint",
}

Body

string

A friendly name for your webhook endpoint.

string

required

The publicly accessible URL of your webhook endpoint. It must use HTTPS and have a valid SSL certificate.

boolean

Set to true to delete the specified webhook endpoint.

Response

200 OK
{
    "endpoint": {
        "eventEndpointId": "e7b8f9c2-3d4a-4b5c-8e9f-1a2b3c4d5e6f",
        "name": "My Webhook Endpoint",
        "url": "https://example.com/your-webhook-endpoint",
        "secret": "your-secret-token"
    }
}

object

Details of the registered webhook endpoint.

Hide properties

string

Unique identifier for the webhook endpoint.

string

Friendly name for the webhook endpoint.

string

The URL of the webhook endpoint.

string

The secret token used for authenticating webhook requests.

Verify webhooks

To ensure that incoming webhook requests are from iinked Sign, you can authenticate them using a secret token. When you register your webhook endpoint, a secret token is generated and included in the response. All notifications will include a X-Syngrafii-Signature header that you can use to authenticate each callback.

X-Syngrafii-Signature: 4d3nJjEP4JJXZBGZROEQKQr4w3E=

You can re-compute the signature by using the endpoint secret token to compute a HMAC-SHA256 hash of the endpoint URL concatenated with the raw JSON content. The URL must match exactly including case and any trailing slashes.

Example in Node.js
Example in C#

app.use(express.json({
    verify: (req, res, buf) => {
        req.rawBody = buf;
    }
}));

function verifySignature(req) {
    const url = process.env.WEBHOOK_ENDPOINT; // iinked Sign Endpoint URL (must match exactly)
    const secret = process.env.WEBHOOK_SECRET; // iinked Sign Endpoint Secret token
    const signatureBase64 = req.headers['x-syngrafii-signature']; // iinked Sign Signature (Node.js header names are lowercased)
    const rawBody = req.rawBody; // Raw body buffer (set in the express.json verify function)

    if (!url || !secret || !signatureBase64 || !rawBody) return false;

    const signatureBuff = Buffer.from(signatureBase64, 'base64'); // Convert base64 to bytes
    const secretBuff = Buffer.from(secret, 'utf8'); // Convert secret to bytes (use utf8, do not use hex)
    const json = rawBody.toString('utf8'); // Convert rawBody buffer to string
    const dataBuff = Buffer.from(url + json, 'utf8'); // Convert url + json to bytes

    const hmac = crypto.createHmac('sha256', secretBuff);
    const dataSignature = hmac.update(dataBuff).digest();

    return crypto.timingSafeEqual(signatureBuff, dataSignature);
}

async Task<bool> VerifySignature()
{
    var url = Environment.GetEnvironmentVariable("WEBHOOK_ENDPOINT"); // iinked Sign Endpoint URL (must match exactly)
    var secret = Environment.GetEnvironmentVariable("WEBHOOK_SECRET"); // iinked Sign Endpoint Secret token
    var signatureBase64 = Request.Headers.GetValues("X-Syngrafii-Signature").FirstOrDefault(); // iinked Sign Signature
    var json = await Request.Content.ReadAsStringAsync(); // Unformatted JSON content
    
    if (string.IsNullOrEmpty(url) || string.IsNullOrEmpty(secret) || string.IsNullOrEmpty(signatureBase64) || string.IsNullOrEmpty(json)) return false;

    var signatureBuff = Convert.FromBase64String(signatureBase64); // Convert base64 to bytes
    var secretBuff = Encoding.UTF8.GetBytes(secret); // Convert secret to bytes (use utf8)
    var dataBuff = Encoding.UTF8.GetBytes(url + json); // Convert url + json to bytes

    var hmac = new HMACSHA256(secretBuff);
    var hash = hmac.ComputeHash(dataBuff);
    
    return hash.SequenceEqual(signatureBuff);
}

If your server-side platform automatically deserializes the JSON content, you will have to add a handler to the request pipeline to perform authentication of the event notification content before deserialization occurs or as in the example above read the request content directly and manually deserialize the JSON afterwards.This is because the signature is computed using the raw JSON content as it was sent and any changes to the content such as whitespace formatting or property ordering will result in a different hash value.

Getting started

Guides

API

Webhooks

Reference

Create a webhook endpoint

Register your webhook endpoint

Authenticate requests (optional)

Create endpoint via iinked Sign

Create endpoint via API

Request

Body

Response

Verify webhooks

​Subscribe to webhooks

Create a webhook endpoint

Register your webhook endpoint

Authenticate requests (optional)

​Create endpoint via iinked Sign

​Create endpoint via API

​Request

​Body

​Response

​Verify webhooks

Subscribe to webhooks

Create endpoint via iinked Sign

Create endpoint via API

Request

Body

Response

Verify webhooks