This guide provides technical instructions for configuring and managing IUSign Webhooks to enable real-time, asynchronous communication between IUSign and your internal systems.
Prerequisites
- Active IUSign account with API/Webhook access enabled (Growth+).
- A publicly accessible endpoint (HTTPS) capable of receiving and processing POST requests.
- Understanding of JSON payload structures and HTTP status codes.
Strategic Overview
Webhooks are a critical component of high-performance document automation. Instead of repeatedly querying (polling) the IUSign API for status updates, Webhooks allow IUSign to proactively "push" event data to your servers the moment a change occurs (e.g., when a document is signed or an envelope is completed). This event-driven architecture significantly reduces API overhead, ensures real-time system synchronization, and allows your internal workflows (CRM updates, database entries, or automated notifications) to trigger instantaneously upon document execution.
Implementation Sequence
1. Activating the Webhook Gateway
Navigate to the Developers section in the primary sidebar and select Webhooks. Select Add Endpoint to initialize the configuration wizard.
2. Endpoint Specification and Governance
Provide the following parameters to define your webhook listener:
- Destination URL: The HTTPS endpoint on your server where IUSign will dispatch payloads.
- Event Selection: Choose the specific triggers that should initialize a webhook dispatch:
envelope.sent: Dispatched when an invitation is successfully sent.recipient.signed: Dispatched every time an individual signature is executed.envelope.completed: Dispatched when the final signature is collected.envelope.voided: Dispatched when a transaction is invalidated.
3. Payload Integrity and Security
Every webhook dispatch includes a Secret Signature in the HTTP header (X-IUSign-Signature).
- Verification: Your server should use this secret to compute an HMAC hash of the payload and compare it to the header. This ensures the request originated from IUSign and has not been tampered with in transit.
4. Testing and Deployment
Utilize the Test Webhook action to dispatch a sample payload to your endpoint.
- Success Criteria: Your server must respond with an HTTP
200 OKstatus code within 5 seconds to acknowledge successful ingestion. - Failure Handling: If your server returns an error (4xx/5xx) or times out, IUSign will implement an exponential backoff retry policy (see below).
Technical Specifications: Delivery and Retries
| Feature | Technical Detail |
|---|---|
| Payload Format | JSON (UTF-8). |
| Transport Protocol | HTTPS (TLS 1.2+ required). |
| Retry Policy | Exponential backoff over 24 hours (up to 8 attempts). |
| Timeout Threshold | 5,000ms (5 seconds). |
| User Agent | IUSign-Webhook-Manager/1.0 |
Security Best Practices for Enterprise Integrations
- HTTPS Mandate: IUSign will only dispatch webhooks to secure HTTPS endpoints to prevent credential leakage.
- Payload Signature Validation: Always validate the
X-IUSign-Signatureto protect against SSRF and spoofing attacks. - Idempotency: Ensure your listener is idempotent (i.e., processing the same payload twice does not cause duplicate side effects) to handle potential retry scenarios.
- IP Whitelisting: Restrict incoming traffic on your webhook port to IUSign's verified outbound IP ranges (contact support for the current list).
Diagnostic and Resolution Protocols
| System Exception | Probable Cause | Resolution Protocol |
|---|---|---|
| Webhooks disabled | Excessive delivery failure | If your endpoint consistently returns 5xx errors, IUSign will automatically disable the webhook. Fix your endpoint and select Re-enable in the dashboard. |
| Payload signature mismatch | Incorrect secret | Ensure your server is utilizing the current Webhook Secret displayed in the IUSign dashboard for hash computation. |
| 404 Not Found | URL misconfiguration | Verify the destination URL is correct and that your server route is active. |