Webhook Callbacks
Formstack provides Integrators with the ability to be notified when an event takes place within Sign.
Warning!
Currently Webhook Callbacks works only for documents sent through integrations. It will not work if document is added via Formstack Sign UI.
Webhook Callback Request Format
The format for events sent to your callback URL is an application/json POST request, with the event details in the request body.
Callback POST Headers
| Header | Description |
|---|---|
| Content-HmacSHA256 | Contains the HMAC SHA256 Hash of the request body using your apiAccessKey as the seed. This hash can be used to validate that the event received by your callback endpoint was transmitted by InsureSign and the contents of the body were not modified during transmission. |
| Content-Type | Specifies the format of the request body. |
Request Body
The following is the format of the InsureSign Webhook Callback Event notification found on the POST request body.
{
"id": "f5a317cf-38a3-4342-8d98-bf58df0e865a",
"eventDateTime": 1544715978401,
"documentId": "9fb73328-a0e9-40c7-81ce-c7d2f7a2d70911545",
"eventType": "FINALIZED",
"lastSendDateTime": 1544715978501
}| Field | Type | Description |
|---|---|---|
| id | String | Unique identifier for the Webhook Event. |
| eventDateTime | Long | A number representing the Unix epoch in which the event transpired in the InsureSign system. |
| documentId | String | The unique identifier for the document that experienced the event. |
| eventType | String | The type of event that was recorded. See [InsureSign Webhook Callback Events] for a complete list. |
| lastSendDateTIme | Long | A number representing the Unix epoch which represents the latest attempt to transmit the event to the Integration Callback Url. |
Responding To Webhook Callbacks
Each integrator callback endpoint will be required to return a 200 HTTP response code, otherwise, the callback will be considered a failure and will flow through the following retry strategy. Each attempt to transmit the InsureSign event to the integrator’s callback will set the lastSendDateTime with the Unix epoch representing the moment the attempt was made. The last response from their integrator callback will be recorded. All callback events associated with an integrator can be retrieved by Integration Webhook Event List.
Retry Intervals:
- 30 seconds
- 1 minute
- 3 minutes
- 5 minutes
- 7 minutes
Using Webhooks
Integration Configuration
To receive a Webhook Callback for Formstack Sign events you will first need to update your Integration profile with a callback URL. The URL will be used to make POST requests with data relating to the event that took place.
Copy integrationId from API Access Tab in Formstack Sign
Refer to API Docs
Please refer to API Reference
PUT /integrations/{integrationId}
Event Subscription
Before you can begin receiving event notifications you must be subscribed to one or more InsureSign events. To subscribe use this POST request to indicate which event(s) you would like to receive notifications.
Refer to API Docs
Please refer to API Reference for
POST /subscriptions
Supported Callback Events
The following request will retrieve the list of supported Webhook Callback Event Types. Use the event name in the Event Subscription to subscribe to a Formstack Sign Webhook Event.
| Name | Description |
|---|---|
| SIGNED | Callback each time a participant signs a document. |
| SIGNER_CANCELLED | Callback each time a participant declines to sign a document. |
| SENDER_CANCELLED | Callback when the sender cancels a document signature request. |
| FINALIZED | Callback when all participants have signed a document. |
| DOCUMENT_COPY_TO_ALL | Callback when a copy of the document has been sent to all participants. |
| DOCUMENT_SENDER_CREATED | Callback when a document is created. |
| DOCUMENT_VIEWED | Callback when a document has been viewed. |
| EMAIL_SENT | Callback when an e-mail is sent to a participant. |
| SERVICE_AGREEMENT | Callback when a signer agrees to the InsureSign service agreement. |
| DOCUMENT_CREATED | Callback when a document is created. |
| DOCUMENT_PDF_DOWNLOADED | Callback when the finalized document is downloaded. |
| SIGNING_LINK_REQUESTED | Callback when a signing link is requested for a document. |
| READY_FOR_FIELD_PLACEMENT | Callback when a document is submitted and is ready to have participants/fields placed. |
List available also at GET /webhooks/events
List Of Subscribed Events
Retrieve all of an Integrators Webhook Callback Event Subscriptions.
Refer to API Docs
Please refer to API Reference for
GET /integrations/{integrationId}/subscriptions
Webhook Callbacks History
Retrieve all Webhook Callback Events recorded for an Integrator. This allows Integrators to perform an audit of the events they have received against all of the notifications InsureSign has attempted to transmit.
Refer to API Docs
Please refer to API Reference for
GET /integrations/{integrationId}/webhooks
Un-Subscribing from Event
Un-subscribe from an InsureSign Webhook Callback Event.
Refer to API Docs
Please refer to API Reference for
DELETE /integrations/{integrationId}/subscriptions/{subscriptionId}DELETE integrations/{integrationId}/subscriptions/{subscriptionId}
Updated 3 days ago