Webhook Integration

Comprehensive event types:

Form Events:

• form.completed: Form filling session completed successfully
• form.failed: Form filling session failed
• form.abandoned: User started but didn't complete form

Batch Events:

• batch.started: Batch processing job started
• batch.completed: Batch job finished successfully
• batch.failed: Batch job failed
• batch.progress: Progress update (every 10% completion)

User Events:

• user.invited: New user invited to workspace
• user.joined: User accepted invitation
• user.removed: User removed from workspace

Subscription Events:

• subscription.upgraded: Plan upgraded
• subscription.downgraded: Plan downgraded
• subscription.canceled: Subscription canceled

Error Events:

• error.occurred: System error during processing
• quota.exceeded: Usage quota exceeded
• payment.failed: Payment processing failed

Custom Events (Enterprise):

• Define custom event types for organization-specific workflows

Event Filtering: Subscribe only to events you need - reduces noise and processing overhead.

Robust retry mechanism:

Retry Schedule:

1. Immediate: First attempt when event occurs
2. +1 minute: If first attempt fails (network error, timeout, 5xx response)
3. +5 minutes: Second retry
4. +15 minutes: Third retry
5. +1 hour: Fourth retry
6. +6 hours: Final retry

Success Criteria:

• HTTP 200-299 response code
• Response received within 30 seconds

Failure Criteria:

• HTTP 4xx/5xx error
• Timeout (>30 seconds)
• Network error (DNS, connection refused)

After Final Retry:

• Event marked as "Failed"
• Admin receives email notification
• Event stored in webhook logs for 30 days
• Can manually retry from webhook dashboard

Best Practice:

• Implement idempotency: Handle duplicate webhook deliveries gracefully
• Use event_id field to detect and ignore duplicates
• Example: If event_id already processed, return 200 without re-processing

Monitoring: Webhook dashboard shows delivery success rate, helps identify systemic issues.

Yes! Comprehensive testing tools:

Test Webhook:

1. Configure webhook with endpoint URL
2. Click "Send Test Event"
3. System sends test payload to your endpoint
4. View response and delivery status in real-time

Test Payload Example:

{
  "event": "test.webhook",
  "timestamp": "2024-02-16T10:00:00Z",
  "data": {
    "message": "This is a test webhook from Instafill.ai"
  }
}

Testing Checklist:

• ✅ Endpoint URL accessible from internet
• ✅ HTTPS certificate valid
• ✅ Signature verification working
• ✅ Response time < 30 seconds
• ✅ Returns HTTP 200 OK

Local Testing (Development):

• Use ngrok or similar to expose local dev server
• Configure webhook with ngrok URL
• Trigger test events, debug locally

Webhook Playground:

• Web-based interface to construct and send test payloads
• Modify event data to test edge cases
• Useful for QA and development

Safety: Test webhooks don't affect production data or trigger real workflows.

Multi-layered security approach:

1. Signature Verification (Required):

# Verify HMAC signature
import hmac
import hashlib

secret = "your_webhook_secret"
signature = request.headers["X-Instafill-Signature"]
payload = request.body

expected_sig = f"sha256={hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()}"

if not hmac.compare_digest(signature, expected_sig):
    return 401  # Unauthorized

2. IP Allowlisting:

• Restrict webhook endpoint to Instafill.ai IPs only
• IP ranges: 52.1.2.0/24, 54.3.4.0/24 (check docs for current ranges)
• Firewall rule: Only accept from these IPs

3. HTTPS Only:

• Never use HTTP endpoints
• Valid SSL certificate required
• TLS 1.2+ enforcement

4. Rate Limiting:

• Limit webhook requests per minute from single IP
• Prevents DOS attacks
• Example: Max 100 webhooks/minute per source IP

5. Input Validation:

• Validate event types: Only process expected events
• Validate payload structure: Ensure required fields present
• Sanitize data: Prevent injection attacks if storing in database

6. Idempotency:

• Store processed event_ids
• Reject duplicate events (replay attacks)
• 24-hour idempotency window

Example Secure Endpoint:

@app.route('/webhook', methods=['POST'])
def webhook():
    # 1. Verify signature
    if not verify_signature(request):
        return 401

    # 2. Check source IP
    if request.remote_addr not in ALLOWED_IPS:
        return 403

    # 3. Check idempotency
    event_id = request.json['event_id']
    if already_processed(event_id):
        return 200  # Acknowledge but don't reprocess

    # 4. Validate payload
    if not valid_payload(request.json):
        return 400

    # 5. Process event
    process_event(request.json)
    mark_processed(event_id)

    return 200

All layers together provide defense-in-depth security.

Yes! Flexible webhook routing:

Workspace-Level Webhooks:

• Configure unique webhook URL per workspace
• Example:
  • Sales Workspace → https://crm.com/webhooks/sales
  • Marketing Workspace → https://crm.com/webhooks/marketing
  • Support Workspace → https://help.com/webhooks/support

Organization-Level Webhooks:

• Single webhook receives events from all workspaces across the organization
• Payload includes workspace_id field for routing
• Useful for centralized event processing

Event-Specific Webhooks:

• Different URLs for different event types
• Example:
  • form.completed events → CRM webhook
  • batch.finished events → Data warehouse webhook
  • error.occurred events → Monitoring system webhook

Conditional Webhooks:

• Send webhooks only when conditions met
• Example: Only send form.completed webhook if form total > $1,000
• Reduces unnecessary webhook traffic

Configuration UI:

1. Select workspace
2. Add webhook
3. Choose scope: "This workspace only" or "All workspaces"
4. Select events
5. Set endpoint URL
6. Add conditions (optional)

Granular control ensures webhooks go where needed without noise.