Event-Driven Webhook Handler

Loading patterns…

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

Important

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".

Visual Flow

When to Use This Pattern

How It Works

Implementation Guide

Tips & Best Practices

Related patterns

API Polling with Change Detection

Change Data Capture Stream

Reverse ETL