Introduction to Webhooks

Webhooks are custom HTTP callbacks that activate upon specific events within the InsCipher platform, such as status updates or payment changes. When an event occurs, InsCipher transmits data to a customer-specified URL, enabling seamless integration and automation between web services. This eliminates the need for polling, optimizing efficiency in surplus lines tax filing and compliance.

This documentation covers the configuration, testing, and maintenance of webhooks, including available system events, authentication, and security.

Webhook Categories

Webhook Categories group event types by InsCipher entity:

Transaction
Batch
Taxes and Fees

Available Event Types

You can subscribe to one or many of the following event types:

Event Name	Event Description
Transaction Status Updated to 'Filed'	Transactions successfully filed with the state.
Batch Status Updated to 'Processed'	A batch of transactions moved to 'processed' state.
Stamping Fee Paid Date Updated	The paid date of a Stamping Fee has been updated.
SL Tax Paid date Updated	The paid date of a Surplus Lines Tax has been updated.
SLA Transaction Number Updated	A single SLA Transaction Number has been updated.
State Stamp Wording Updated	Any state stamp wording property values have been updated.

Responses

Successful responses are indicated by a 200 status code.

Retries

In case of a failed delivery, InsCipher attempts to deliver the data 3 times before sending an email notification for manual data import.

After Failure #	Webhook / System Behavior
1	Immediate retry
2	Retry after 30 minutes from Failure #1
3	Retry after 30 minutes from Failure #2
4	Email notification with instructions for manual import.

Communications

Currently, notifications are supported only when a request fails after the 3rd retry. You can configure System Notifications or Email Notifications.

System Notification

A notification in the InsCipher system notifications tray.

System Notification template

System Notification

Example: ***Webhook Transaction status updated to 'Filed' has failed*** `This is a notification to advise you that the 'Transaction Status updated to Filed webhook, which was configured for InsCipher Demo, has failed to delvier to the following endpoint: https://test.api.mockbin.io/. ***Request Details*** Failed Event ID: 5225 Response status: 401 Response body / message: Client error 'POST https://test.api.mockbin.io/' resulted in a '401 Unauthorized' response: { "message:" "Hello world } Please review the following: Ensure that your endpoint is accessible and can process POST requests. Validate your authentication credentials. Review any rate limiting configurations or firewall settings. If you are still having trouble, please contact the support team immediately at [email protected]

Email Notification

An email notification sent to subscribers configured in the settings.

Email Notification template

System Notification

Example: Hello (username),

This is a notification to advise you that the "webhook.transaction.status.filed' webhook, which was configured for Demo Agency, has failed to deliver to teh following endpoint: https://test.api.mockbin.io/

Transaction details:

Webhook title: Test webhook
Webhook Event: webhook.transaction.status.filed
Your Endpoint URL: https://test.api.mockbin.io/
Timestamp: 2025-01-02 12:10:20
Response status: 401
Response body: "Client error: 'POST https://test.mockbin.io/' resulted in a '401 Unauthorized' response: "message": "Hello World"

Please review the following:

Ensure that your endpoint is accessible and can process POST requests.
Validate your authentication credentials
Review any rate limiting configurations or firewall settings. If you are still having trouble, please contact the support team immediately at [email protected]

Limitations

Webhook requests are processed through a system queue. While there are no rate limits, report any delays in responses via a support ticket.