Event-Driven Webhook Handler
Receive real-time events from external systems via webhooks, validate them, and trigger the appropriate workflow response. The foundation of reactive automation.
On this page
Visual Flow
Rendering diagram…
When to Use This Pattern
Use event-driven webhooks when:
- An external system can send HTTP notifications when something happens
- You need real-time response (not batch/polling)
- You're integrating with SaaS platforms that offer webhook support (Stripe, GitHub, Jira, ServiceNow, etc.)
- You want your Nintex workflows to react instantly to external events
How It Works
| Step | Component | Action |
|---|---|---|
| 1 | External system | Event occurs (payment received, issue created) |
| 2 | External system | Sends HTTP POST to your webhook URL |
| 3 | Webhook endpoint | Receives, validates, and acknowledges the request |
| 4 | Router | Inspects the event type and routes to the appropriate workflow |
| 5 | Workflow | Processes the event (creates task, updates record, sends notification) |
Implementation Guide
Step 1: Create the Webhook Endpoint
In Nintex Workflow Cloud, use a Start event: External start to create a webhook URL. The platform gives you a unique URL like:
https://your-tenant.workflowcloud.com/api/v1/workflow/published/xxxxx-xxxxx/start
Step 2: Validate Incoming Requests
Never trust incoming webhooks blindly:
| Validation | How |
|---|---|
| Signature verification | Check the HMAC signature in the request header against your shared secret |
| Source IP whitelist | Only accept requests from known IP ranges |
| Payload schema | Validate that required fields exist and have correct types |
| Idempotency check | Check if you've already processed this event ID |
| Timestamp check | Reject events older than 5 minutes (replay protection) |
Step 3: Acknowledge Quickly
The external system expects a fast response (usually within 5-30 seconds):
- Respond immediately with 200 OK
- Process asynchronously — don't do heavy processing in the webhook handler
- If you can't process now, queue the event and process it later
Step 4: Route by Event Type
Most webhook providers send different event types:
| Event Type | Workflow Action |
|---|---|
payment.succeeded | Update order status, send receipt |
payment.failed | Notify customer, retry payment |
invoice.created | Sync to accounting system |
customer.updated | Update CRM record |
subscription.cancelled | Trigger retention workflow |
Step 5: Handle Failures and Retries
Webhook providers typically retry failed deliveries:
- Return 200 for successfully received events (even if processing fails later)
- Return 4xx only if the request is malformed
- Return 5xx if you want the provider to retry
- Build your own retry for processing failures using the Retry with Exponential Backoff pattern
Tips & Best Practices
Always respond to webhooks within the timeout period (usually 5-30 seconds). If your processing takes longer, accept the webhook, queue the work, and process asynchronously.
- Log everything. Store the raw webhook payload, headers, and your processing result. When something goes wrong, you need to replay the exact request.
- Use a dead letter queue. Events that fail processing repeatedly should be moved to a dead letter queue for manual investigation, not silently dropped.
- Monitor delivery gaps. Webhook providers show delivery history. Check periodically for failed deliveries that weren't retried.
- Handle out-of-order events. Events might arrive out of order. Your processing logic should be resilient to receiving "invoice.paid" before "invoice.created".
Related patterns
API Polling with Change Detection
Periodically check an external system for changes and trigger workflows when new or updated records are detected. The reliable alternative when webhooks aren't available.
Change Data Capture Stream
Stream row-level changes out of a database in near real-time using the transaction log. No polling, no app changes — downstream systems get inserts, updates, and deletes as they happen.
Reverse ETL
Push modelled data from your warehouse back into the SaaS tools that business teams use every day — CRM, marketing, support — so they can act on analytics without a BI detour.