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.
1
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).
2
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.
3
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.
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.
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.
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.
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#
Copy
Ask AI
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);}
Copy
Ask AI
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.
