Webhooks
InsighIQ uses webhooks to send programmatic updates about your creator’s data when it is added, updated, or deleted. For example, a webhook event account.added is sent when a creator links a new work platform account.
We highly recommend using webhooks for a smooth and optimized integration. Webhooks notify you of changes asynchronously, enabling real-time updates that would otherwise be missed.
Format
Environment Separation: Webhooks are configured individually for staging, and production environments.
URL Requirements: The webhook URL must follow the standard format https://domain.com/path and have a valid SSL certificate.
Payload: Webhooks send POST requests with raw JSON payloads.
Payload Considerations: When the payload includes a list of IDs, it is limited to a maximum of 100 IDs. Multiple webhook events will be sent to accommodate all IDs in case of large data changes. For best practices on handling multiple webhooks, refer to Webhook Handling Guide
Security
We offer two security mechanisms for webhooks; Signature verification and IP verification/blocklisting & allow-listing.
Signature verification
Use the secret from your API credentials to validate webhook requests. While this is optional, it is strongly recommended as it ensures that the webhook request originates from InsighIQ.
The secret is sensitive information and should never be exposed publicly.
The number of signatures in the header is equal to the number of active secrets. Multiple signatures are usually encountered during key rotation. Below is an example header:
Webhook-Signatures: "<signature-1>,<signature-2>"The Webhook-Signatures header contains one or more signatures, generated using HMAC-SHA256 algorithm with your secret as the key and the raw webhook body as the message.
You can validate the webhook signature using an HMAC as shown below. In case of multiple signatures, expect to match at least one signature using at least one active secret.
Ensure the webhook body passed to the HMAC function is the raw webhook body, not a parsed or cast version.
const crypto = require("crypto")
const key = webhook_secret
const message = webhook_body // raw webhook request body, don't use parse, to_string, stringify, dump, etc.
const received_signature = webhook_signature
const expected_signature = crypto.createHmac('sha256', key).update(message).digest('hex') // create hmac of the webhook body using sha 256
if !crypto.timingSafeEqual(expected_signature, received_signature) // secure hmac comparison method
throw Error // signature mismatch due to unauthentic webhook callIP verification
Accept the webhook requests originating only from the following IP addresses: Staging: 3.211.223.93, 44.216.173.40 Production: 3.211.223.93, 44.216.173.40
Note: The IP addresses are subject to change
Timeout
Webhook requests time out after 5 seconds. If no response is received within this timeframe, the delivery is marked as failed, and retry mechanisms are triggered.
Upon receiving a webhook, verify the signature and immediately respond with a 200 OK as acknowledgement and then process the payload asynchronously in a separate thread.
The webhook timeout window is small, avoid making webhook processing dependent on other processes or API calls.
Retry Mechanism
InsighIQ follows an at-least-once delivery policy to ensure webhooks are not missed. If your server fails to respond successfully (non 200 HTTP status) or timeouts, the webhook is retried up to three times:
Retry Intervals:
First Retry: 60 seconds after failure
Second Retry: 5 minutes after the first retry
Third Retry: 6 hours after the second retry
A webhook is resent up to a maximum of 3 times, at an interval of 60 seconds, 5 minutes, and 6 hours respectively, from the previous failure. If no successful response is received even after 3rd retry (total of 4 tries), InsightIQ will stop retrying. You will need to fetch the response or check the request status using the relevant GET API endpoints.
Idempotency
The Retry policy assumes the webhook event has not been processed and is sent again. Ensure your server is configured to handle duplicate events multiple times.
We provide a unique id with all our webhook payloads to help you remove duplicate events or report errors to us for better and faster support.
Order of events
Ideally, webhooks are recieved in the order the events occur. For example: While fetching a creator's identity information, the webhooks should be fired in the following order
`PROFILES.ADDED`
`PROFILES.UPDATED`However, this is not guaranteed. Configure your webhook handler to not expect delivery in any order.
Delivery semantics
While webhook events are delivered within a few seconds, we do not recommend relying on webhooks for time-sensitive events. For business-critical, synchronous use cases, please poll our APIs.
Setting up webhooks
Our Developer dashboard is the easiest way to manage your webhooks. For programmatic management of webhooks, use Webhook APIs. Below section details how to manage webhooks using our APIs.
Creating webhooks
You can create webhooks using create a webhook API.
You can create a maximum of 3 webhooks in each environment. The webhooks within the same environment can include same or overlapping events but can not have duplicate URLs. Having separate set of webhooks for each environment helps in smooth setup and testing.
Listing webhooks
List all available webhooks using the Retrieve all webhooks API.
Getting details of a webhook
Get the details of a particular webhook using the Retrieve a webhook API.
Editing or updating a webhook
Update a webhook using Update a webhook API.
If webhooks get deactivated after unsuccessful deliveries or timeouts. Use this API to reactivate the webhook after fixing the issues at your end.
Deleting a webhook
Delete a particular webhook using Delete a webhook API.
Testing webhooks
To test the webhooks in staging mode, we provide a mechanism to simulate the webhooks with custom data as if it were coming from InsighIQ using Send webhook notification API.
Here are some popular request interceptors to test and debug webhook requests. Once testing is complete, delete or disable the test webhooks: Webhook.site Beeceptor Pipedream
Example Use Cases
Capturing user profile information
When a creator links their work platform account with InsighIQ, profile data is fetched from the work platform.
The PROFILES.ADDED webhook event notifies you once the profile information of the creator is synced and their identity is established.
Capturing engagement metrics
When a creator links their work platform account with InsighIQ, creator's content information and engagement metrics are fetched.
The CONTENTS.ADDED webhook event notifies you when the creator's content and engagement data are first available.
The CONTENTS.UPDATED webhook event notifies you of updates to engagement metrics. Use the event payload to fetch updated data for the specific content IDs.