Instnt Webhooks

Instnt Webhooks allow you to effortlessly monitor events within your Instnt account and trigger automatic reactions in your integration.

By utilizing webhooks, Instnt ensures that your application receives timely notifications whenever an event occurs in your account. Webhooks are particularly valuable for handling asynchronous events, such as confirming customer payments, managing charge disputes, or processing successful recurring payments.

Getting started with webhooks in your Instnt integration is a breeze. Just follow these three simple steps:

1. Create a webhook endpoint on your server.
2. Verify the functionality of your endpoint using the provided test.
3. Register the endpoint with Instnt to make it live and active.

It's important to note that while webhooks offer significant benefits, not all Instnt integrations require them. For further insights into the concept of webhooks and determining their suitability for your integration, continue reading below.

About Webhooks

Webhooks encompass a set of components that collaboratively establish a notification and reaction system within a broader integration framework.

To illustrate their function, let's draw a metaphorical comparison: think of webhooks as a phone number Instnt dials to apprise you of activities occurring in your Instnt account. These activities can range from the creation of a new customer to funds being disbursed to your bank account. In this analogy, the webhooks endpoint assumes the role of the person answering the call, capable of taking specific actions based on the received information.

In practical terms, the webhooks endpoint represents additional code hosted on your server, potentially written in languages like Ruby, PHP, Node.js, or any language of your preference. It is associated with a dedicated URL, such as "https://example.com/webhooks". Notifications from Instnt are transmitted as Event objects, encapsulating essential details about the recent occurrence. These details include:

• ID: An event identifier with global uniqueness (e.g., evt_fh238sh3).
• Event Name: A user-friendly description of the event, for instance, "Document image.png submitted."
• Event Type: Categorization of the event, like "document.submitted."
• Event Data: JSON with relevant event data.

By leveraging these event details, the webhooks endpoint can execute any necessary actions, such as flagging a transaction for manual review. Webhooks present a powerful mechanism that seamlessly integrates within your system, enabling real-time responses to events and facilitating appropriate actions.

Types of Events

Instnt will continue to update new events with each subsequent release.

When to use Webhooks

Webhooks are essential for managing events within an Instnt account, accommodating both synchronous and asynchronous scenarios.

In an Instnt account, numerous events produce synchronous results, delivering immediate and direct responses to executed requests. These events are tightly linked to your code's execution, resulting in instant outcomes.

However, certain events occur asynchronously, not directly triggered by your code's execution and happening at a later time. Examples include the completion of the Document Verification process or revisions to decisions made within a Workflow.

Instnt relies on webhooks to inform your integration about changes in the status of an object, allowing your integration to take subsequent steps accordingly. The specific actions your webhooks endpoint may undertake vary depending on the specific event. This flexibility ensures that your integration responds appropriately to the event's nature and requirements.

Additionally, webhooks have broader applications. They can be leveraged to provide state updates and API responses to services or systems that rely on Instnt data for tasks such as replication, analytics, or alerting.

By effectively utilizing webhooks, you can optimize your Instnt integration, facilitating efficient communication and enabling timely actions based on significant events within your account.

Building Webhooks

Authorized users, including End User Administrators and Instnt Staff, have the ability to create Webhooks in the Settings/Webhooks section of the Dashboard.

List of Webhooks

• URL

• Enabled

Add/Edit Endpoint

• Endpoint URL

• Description

• Events to send 

• Forms/Workflows: Webhooks can be associated with zero or more forms/workflows.

  • If no forms are mapped, all events will be sent to the webhooks.

  • If no forms are mapped, no events will be sent to the webhooks. 

Signing Webhooks

Each payload sent to the webhook is signed with an Instnt Private Key in the following manner:

• Digest is calculated off the message

• The digest is signed with Instnt Private Key

• The signature is sent as an HTTP Header ‘Instnt-Signature: {signature}’

The code behind your endpoint should:

• Verify the signature using the Instnt Public Key

• Check the signed Timestamp to ensure it isn't too old

All webhooks are signed using Instnt Private key and RSA PKCS#1 v1.5 standard, and the Signature is sent with each webhook event in the HTTP header “Instnt-Signature”.

The receiving party should validate the signature to reject requests that are not coming from Instnt.

To validate the signature:

• Decode the signature from Base64

• Calculate hash digest from the the payload

• Validate the signature against the hash digest using RSA PKCS#1 v1.5 algorithm

For more information related to decrypting Instnt's Private Key, refer to Data Encryption and Decryption.

The following examples display verified signatures.

Notes:

• raw_request_payload is unmodified, unparsed POST payload received to the webhook URL.

• request_headers are HTTP headers.

Python

from Crypto.Signature import PKCS1_v1_5
from Crypto.PublicKey import RSA
from Crypto.Hash import SHA256

PUBLIC_KEY = """
{Instnt Public Key}
"""

def verify_signature(self, raw_request_payload, request_headers):
digest = hashlib.sha256(payload).digest()
encoded_signature = request_headers.get("Instnt-Signature")
signature = base64.b64decode(encoded_signature)

public_key = RSA.import_key(PUBLIC_KEY)
verifier = PKCS1_v1_5.new(public_key())
verified = verifier.verify(SHA256.new(digest), signature)

return verified

TypeScript

import { readFileSync } from 'fs';
import { resolve } from 'path';
import { createVerify, createHash } from 'crypto';

// Read public key from file
const public_key = readFileSync(
resolve(__dirname, 'instnt-sandbox-key.pem'),
'utf-8'
);

export const verify_signature = (payload: string, signature: string) => {
// Create SHA256 hash digest from the payload
let hash = createHash('sha256').update(payload).digest().toString('base64');

console.log(`Hash: ${hash}`);

// Verify signature
const isValid = createVerify('RSA-SHA256')
.update(hash, 'base64')
.verify(public_key, signature, 'base64');

console.log(`Signature valid: ${isValid}`);

return isValid;
};